@openlines/opl-pi-sht 0.2.12 → 0.3.0

package/extensions/opl-configurator/configurator.ts

@@ -0,0 +1,148 @@
+import type { ExtensionContext, KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import type { TUI } from "@earendil-works/pi-tui";
+
+// The configurator seam. Instrumented extensions publish entries on this
+// globalThis array; the shell reads it lazily when /configurator runs, so
+// extension load order does not matter. The entry shape is duplicated by hand
+// on the publishing side (e.g. opl-footer/configure.ts) because install.sh
+// copies one extension directory at a time and cross-directory imports are
+// forbidden.
+export const CONFIGURATOR_REGISTRY_KEY = "__oplConfiguratorTabs";
+
+/** What the shell hands to a tab's factory. */
+export interface ConfiguratorTabApi {
+  ctx: ExtensionContext;
+  tui: TUI;
+  theme: Theme;
+  keybindings: KeybindingsManager;
+  done: (result: void) => void;
+}
+
+/** A component with the same contract as ctx.ui.custom's return value. */
+export interface ConfiguratorTabComponent {
+  render(width: number): string[];
+  invalidate?(): void;
+  handleInput?(data: string): void;
+}
+
+export interface ConfiguratorTab {
+  /** Unique extension id, e.g. "opl-footer". */
+  id: string;
+  /** Single lowercase letter that focuses this tab from anywhere in the shell. */
+  hotkey: string;
+  /** Short tab-bar label, e.g. "Footer". */
+  label: string;
+  create: (api: ConfiguratorTabApi) => ConfiguratorTabComponent;
+}
+
+function isConfiguratorTab(value: unknown): value is ConfiguratorTab {
+  if (typeof value !== "object" || value === null) return false;
+  const entry = value as Record<string, unknown>;
+  return (
+    typeof entry.id === "string" &&
+    entry.id.length > 0 &&
+    typeof entry.hotkey === "string" &&
+    /^[a-z]$/.test(entry.hotkey) &&
+    typeof entry.label === "string" &&
+    entry.label.length > 0 &&
+    typeof entry.create === "function"
+  );
+}
+
+/** Read the registry, dropping malformed entries and duplicate ids/hotkeys. */
+export function readConfiguratorTabs(): ConfiguratorTab[] {
+  const raw = (globalThis as Record<string, unknown>)[CONFIGURATOR_REGISTRY_KEY];
+  if (!Array.isArray(raw)) return [];
+
+  const tabs: ConfiguratorTab[] = [];
+  const seenIds = new Set<string>();
+  const seenHotkeys = new Set<string>();
+  for (const entry of raw) {
+    if (!isConfiguratorTab(entry)) continue;
+    if (seenIds.has(entry.id) || seenHotkeys.has(entry.hotkey)) continue;
+    seenIds.add(entry.id);
+    seenHotkeys.add(entry.hotkey);
+    tabs.push(entry);
+  }
+  return tabs;
+}
+
+export async function showConfigurator(ctx: ExtensionContext): Promise<void> {
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify("/configurator requires TUI mode", "error");
+    return;
+  }
+
+  const tabs = readConfiguratorTabs();
+  if (tabs.length === 0) {
+    ctx.ui.notify("Nothing exposes a /configurator tab yet", "error");
+    return;
+  }
+
+  await ctx.ui.custom<void>((tui, theme, keybindings, done) => {
+    const built: Array<{ tab: ConfiguratorTab; component: ConfiguratorTabComponent }> = [];
+    for (const tab of tabs) {
+      try {
+        const component = tab.create({ ctx, tui, theme, keybindings, done });
+        if (component && typeof component.render === "function") built.push({ tab, component });
+      } catch {
+        // A broken tab must not take the whole configurator down.
+      }
+    }
+
+    if (built.length === 0) {
+      return {
+        render: (width: number) => [truncateToWidth(theme.fg("dim", "No instrumented extensions could be loaded."), width)],
+        invalidate() {},
+      };
+    }
+
+    let activeIndex = 0;
+    const clamp = () => {
+      activeIndex = Math.min(activeIndex, built.length - 1);
+    };
+
+    const focusByHotkey = (data: string): boolean => {
+      if (data.length !== 1) return false;
+      const key = data.toLowerCase();
+      const index = built.findIndex(({ tab }) => tab.hotkey === key);
+      if (index === -1) return false;
+      activeIndex = index;
+      return true;
+    };
+
+    return {
+      render(width: number) {
+        clamp();
+        const tabBar = built
+          .map(({ tab }, index) => theme.fg(index === activeIndex ? "accent" : "dim", `[${tab.hotkey}] ${tab.label}`))
+          .join("  ");
+        const active = built[activeIndex]!;
+        return [
+          truncateToWidth(theme.bold("OPL Configurator"), width),
+          truncateToWidth(tabBar, width),
+          truncateToWidth(theme.fg("dim", "tab hotkey switch · esc close"), width),
+          ...active.component.render(width),
+        ];
+      },
+      invalidate() {
+        clamp();
+        built[activeIndex]?.component.invalidate?.();
+      },
+      handleInput(data: string) {
+        if (matchesKey(data, Key.escape)) {
+          done(undefined);
+          return;
+        }
+        if (focusByHotkey(data)) {
+          tui.requestRender();
+          return;
+        }
+        clamp();
+        built[activeIndex]?.component.handleInput?.(data);
+        tui.requestRender();
+      },
+    };
+  });
+}

package/extensions/opl-configurator/index.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { showConfigurator } from "./configurator.js";
+
+export default function configurator(pi: ExtensionAPI): void {
+  pi.registerCommand("configurator", {
+    description: "Configure instrumented OPL extensions through hotkey tabs",
+    handler: async (_args, ctx) => {
+      await showConfigurator(ctx);
+    },
+  });
+}

package/extensions/opl-ctxtrim/README.md

@@ -1,6 +1,6 @@
 # opl-ctxtrim
 
-Trims the verbose `ctx_*` tool descriptions that the third-party [context-mode](https://github.com/mksglu/context-mode) MCP bridge injects into every provider request. It edits only the serialized outbound payload through Pi's documented `before_provider_request` hook, so the installed context-mode package and its tool execution are never modified.
+Trims description prose for eleven known `ctx_*` tools from [context-mode](https://github.com/mksglu/context-mode) on Pi's outbound provider requests. Provider support handles different encodings of those same tool definitions; it does not expand trimming to other tools or general context. The extension edits the serialized request through `before_provider_request`, leaving the installed context-mode package and tool execution unchanged.
 
 ## Commands, tools, and configuration
 
@@ -8,23 +8,41 @@ No commands, tools, or configuration. Loading the extension is the entire interf
 
 ## What it does
 
-context-mode registers eleven `ctx_*` tools whose descriptions carry multi-paragraph "Think-in-Code" prose, `WHEN`/`WHEN NOT` sections, and worked examples. Those descriptions are serialized into the tool schema on **every** provider request. `opl-ctxtrim` replaces each known tool's top-level description with a concise equivalent and shortens nested JSON Schema parameter descriptions to their first sentence.
+The allowlist covers eleven context-mode `ctx_*` tools whose descriptions carry multi-paragraph "Think-in-Code" prose, `WHEN`/`WHEN NOT` sections, and worked examples. Those descriptions are serialized into the tool schema on **every** provider request. `opl-ctxtrim` replaces each known tool's top-level description with a concise equivalent and shortens nested JSON Schema parameter descriptions to their first sentence.
 
 Preserved exactly: tool names, execution routing, schema structure, `required`, `enum`, `default`, numeric bounds, and strict-mode flags. Only human-readable `description` prose changes.
 
-Supported provider payload shapes:
+### Scope
 
-- OpenAI Responses / Anthropic / Google: `{ name, description, parameters }`
-- OpenAI Chat Completions / Mistral: `{ function: { name, description, parameters } }`
-- Amazon Bedrock Converse: `toolConfig.tools[].toolSpec`
+The curated description table is the whole policy. A tool is trimmed only when its exact name is an own entry in `CTX_DESCRIPTIONS`; inherited JavaScript property names do not match. Matching is by name, not server identity, so another tool using an allowlisted name receives the same substitution:
 
-Any unrecognized payload shape, any non-`ctx_*` tool, and any `ctx_*` tool not in the built-in description map are returned unchanged (fail open). This means a future context-mode release that adds or renames a tool is left untouched at runtime until the extension is updated; the test suite flags such tools for review.
+- New or renamed `ctx_*` tools absent from the table pass through untouched until explicitly reviewed and added.
+- Tools whose names are absent from the table, including built-in Pi tools and other MCP tools, remain unchanged.
+- Unrecognized payload shapes fail open: the original payload is returned.
+
+Adding a tool to the table is a source change, not a configuration; there is no config file to edit.
+
+### Provider tool shapes
+
+Pi serializes the same context-mode tool definitions differently for each provider. These handlers locate the declarations before applying the same eleven-name policy.
+
+| Provider format | Tool name location | Parameter schema location |
+|---|---|---|
+| OpenAI Responses | `tools[].name` | `tools[].parameters` |
+| OpenAI Chat Completions / Mistral | `tools[].function.name` | `tools[].function.parameters` |
+| Anthropic | `tools[].name` | `tools[].input_schema` |
+| Google/Gemini | `tools[].functionDeclarations[].name` | Declaration's `parametersJsonSchema` or `parameters` |
+| Amazon Bedrock Converse | `toolConfig.tools[].toolSpec.name` | `toolSpec.inputSchema.json` |
+
+The locator also accepts `toolSpecifications[]`, `tool_config` wrappers and direct named declarations with `parameters`, `input_schema` or `parametersJsonSchema`. These are structural compatibility paths, not additional tool policies. Messages, system prompts, routing anchors, tool results and indexed content are not trimmed. Unknown shapes are returned unchanged.
+
+A context-mode release that adds or renames a `ctx_*` tool is invisible to the table, and therefore invisible to the savings too. The test suite prints those tools as `uncovered ctx_* tools (review after upgrade)` so the gap is a review item rather than a silent loss. The measured server snapshot was v1.0.169; that number is not a compatibility guarantee.
 
 ## Token savings
 
 ### Reproducible schema measurement
 
-The test suite queries the installed context-mode **v1.0.169** server (11 `ctx_*` tools), serializes its real `tools/list` result as an OpenAI Responses tool array, and compares bytes before and after trimming:
+The test suite queries the installed context-mode server (v1.0.169 at the time of writing, 11 `ctx_*` tools), serializes its real `tools/list` result as an OpenAI Responses tool array, and compares bytes before and after trimming:
 
 | Schema state | Bytes | Change from original |
 |---|---:|---:|
@@ -32,9 +50,20 @@ The test suite queries the installed context-mode **v1.0.169** server (11 `ctx_*
 | Current `opl-ctxtrim` output | 9,152 | **18,867 fewer (67.3%)** |
 | Hypothetical empty descriptions, schemas retained | 4,683 | 23,336 fewer (83.3%) |
 
-The final row is a ceiling, not a recommended configuration. Current replacements retain compact tool guidance and parameter descriptions; empty descriptions would remove another 4,469 bytes but make tool selection and argument construction less reliable. The remaining 4,683 bytes are mostly required schema structure, parameter names, types, enums, bounds, and `required` fields.
+Those three rows are one payload in one shape. The suite also measures the other supported shapes, using the same eleven curated tool names with synthetic verbose descriptions so the comparison across shapes is like-for-like rather than dependent on whatever context-mode happens to ship:
+
+| Shape | Original | Trimmed | Saved |
+|---|---:|---:|---:|
+| OpenAI Chat/Responses array | 21,912 | 5,666 | 16,246 (74.1%) |
+| Google/Gemini `functionDeclarations` | 21,752 | 5,726 | 16,026 (73.7%) |
+
+The 21,912-byte and 21,752-byte originals are synthetic fixtures and are smaller than the 28,019-byte real payload above; do not read them as three views of one number.
+
+So a Gemini request is trimmed like the others instead of passing through whole. All of it is conditional on the curated tools being present: a session without context-mode sends no `ctx_*` declaration, matches nothing in the table, and the payload leaves the extension byte-identical - no saving, no risk.
+
+The empty-description row in the first table is a ceiling, not a recommended configuration: current replacements retain compact tool guidance and parameter descriptions, and emptying them would remove another 4,469 bytes while making tool selection and argument construction less reliable. The remaining 4,683 bytes are mostly required schema structure, parameter names, types, enums, bounds, and `required` fields.
 
-Run `npm run test:opl-ctxtrim` to regenerate the first two rows. It also reports a rough 3-4 bytes-per-token estimate of 4,717-6,289 tokens per request. Treat that as a byte heuristic, not billing data.
+Run `npm run test:opl-ctxtrim` to regenerate the tables. Dividing the 18,867-byte Responses saving by the usual 3-4 bytes per token gives roughly 4,700-6,300 tokens per request. Treat that as a byte heuristic, not billing data; it belongs to the Responses shape, and the other two shapes save 16,246 and 16,026 bytes.
 
 ### Observed provider accounting
 
@@ -70,9 +99,11 @@ Removing or lazily exposing entire `ctx_*` tools could save more than descriptio
 
 ## Architecture
 
-```text
-index.ts   before_provider_request handler; CTX_DESCRIPTIONS map;
-           provider-shape detection; description-only trimming.
-```
+### index.ts
+- before_provider_request handler
+- CTX_DESCRIPTIONS map (the only names ever rewritten)
+- tool-array discovery across provider shapes 
+  - tools[], functionDeclarations, toolSpecifications, toolConfig / tool_config
+- description-only trimming of parameters recursively
 
 Exports `trimPayload`, `CTX_DESCRIPTIONS`, and `shortenParamDescription` for testing. The extension is self-contained and dependency-free.

package/extensions/opl-ctxtrim/index.ts

@@ -1,11 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-// opl-ctxtrim trims the verbose descriptions that the third-party context-mode
-// MCP bridge attaches to its ctx_* tools. It edits only the serialized provider
-// payload in the documented `before_provider_request` hook, so the installed
-// context-mode package (and its tool execution) is never modified. Tool names,
-// schema structure, required fields, enums, defaults, bounds, and strict flags
-// are preserved; only human-readable `description` prose is shortened.
+// opl-ctxtrim trims only the known context-mode ctx_* tool descriptions listed in
+// CTX_DESCRIPTIONS. Provider handlers locate those same definitions in the different
+// request formats Pi emits; they do not widen the tool policy or trim conversation data.
+// Only the serialized payload is edited through before_provider_request. The installed
+// context-mode package, tool execution, names and schema validation rules stay unchanged.
 
 // Concise top-level descriptions for the eleven ctx_* tools shipped by
 // context-mode v1.0.169. Any ctx_* tool NOT listed here is left unchanged so a
@@ -38,7 +37,7 @@ export const CTX_DESCRIPTIONS: Record<string, string> = {
 // Shorten a nested JSON Schema parameter description to its first sentence or
 // line. Only `description` text is touched, never validation keywords.
 export function shortenParamDescription(text: string): string {
-  const firstLine = text.split("\n", 1)[0].trim();
+  const firstLine = (text.split("\n", 1)[0] ?? "").trim();
   const sentenceEnd = firstLine.search(/\.\s|\.$/);
   const clipped = sentenceEnd >= 0 ? firstLine.slice(0, sentenceEnd + 1) : firstLine;
   return clipped.length > 160 ? `${clipped.slice(0, 157).trimEnd()}...` : clipped;
@@ -61,7 +60,7 @@ function shortenSchemaDescriptions(node: unknown): void {
   }
 }
 
-// A tool entry across the three supported provider shapes exposes a name, a
+// A tool entry across the supported provider shapes exposes a name, a
 // holder object carrying `description`, and (optionally) a parameters schema.
 interface ToolView {
   name: string;
@@ -92,12 +91,13 @@ function viewTool(tool: unknown): ToolView | null {
     }
   }
 
-  // OpenAI Responses / Anthropic / Google: { name, description, parameters|input_schema }
+  // OpenAI Responses / Anthropic / Google declarations:
+  // { name, description, parameters | input_schema | parametersJsonSchema }
   if (typeof record.name === "string") {
     return {
       name: record.name,
       descriptionHolder: record,
-      parameters: record.parameters ?? record.input_schema,
+      parameters: record.parameters ?? record.input_schema ?? record.parametersJsonSchema,
     };
   }
 
@@ -106,6 +106,7 @@ function viewTool(tool: unknown): ToolView | null {
 
 // Trim a single tool view in place when it is a known ctx_* tool.
 function trimToolView(view: ToolView): boolean {
+  if (!Object.hasOwn(CTX_DESCRIPTIONS, view.name)) return false;
   const concise = CTX_DESCRIPTIONS[view.name];
   if (!concise) return false;
   if (typeof view.descriptionHolder.description === "string") {
@@ -117,12 +118,31 @@ function trimToolView(view: ToolView): boolean {
   return true;
 }
 
+// Keys that hold a declaration array directly, per provider dialect.
+const DECLARATION_KEYS = ["functionDeclarations", "toolSpecifications"];
+// Keys that wrap tool settings; Google uses camelCase, some gateways snake_case.
+const TOOL_CONFIG_KEYS = ["toolConfig", "tool_config"];
+
+function arraysInto(target: unknown[][], value: unknown, keys: string[]): void {
+  if (!value || typeof value !== "object") return;
+  const record = value as Record<string, unknown>;
+  if (Array.isArray(record.tools)) target.push(record.tools);
+  for (const key of keys) {
+    if (Array.isArray(record[key])) target.push(record[key] as unknown[]);
+  }
+}
+
 // Locate the tool arrays inside a provider payload across supported shapes.
 function toolArrays(payload: Record<string, unknown>): unknown[][] {
   const arrays: unknown[][] = [];
-  if (Array.isArray(payload.tools)) arrays.push(payload.tools);
-  const toolConfig = payload.toolConfig as Record<string, unknown> | undefined;
-  if (toolConfig && Array.isArray(toolConfig.tools)) arrays.push(toolConfig.tools);
+  if (Array.isArray(payload.tools)) {
+    arrays.push(payload.tools);
+    // Google (Generative AI and Vertex) nests declarations one level deeper:
+    // tools: [{ functionDeclarations: [{ name, description, parametersJsonSchema }] }]
+    // and pi-ai emits exactly this shape (pi-ai dist/api/google-shared.js:338).
+    for (const entry of payload.tools) arraysInto(arrays, entry, DECLARATION_KEYS);
+  }
+  for (const key of TOOL_CONFIG_KEYS) arraysInto(arrays, payload[key], DECLARATION_KEYS);
   return arrays;
 }
 

package/extensions/opl-footer/README.md

@@ -4,7 +4,7 @@ A customizable three-row footer for the Pi coding agent. It shows model, path, G
 
 ## Commands, flags, and shortcuts
 
-`/configure-opl` provides six row/side tabs to toggle or reorder standard segments and their trailing separators, applying changes immediately. Press `r` for reorder view, then `,`/`.` to move the selected segment. The `status` segment shows `Working` during agent execution, `Waiting` while Pi tools run, and `Ready` when the agent settles. Colors, icons, literal text, and other options remain JSON-only. Nerd Font detection can be overridden with `FOOTER_NERD_FONTS=1` or `FOOTER_NERD_FONTS=0`.
+`/configurator` opens the `opl-configurator` shell, whose Footer tab (hotkey `f`) provides six row/side tabs to toggle or reorder standard segments and their trailing separators, applying changes immediately. Press `r` for reorder view, then `,`/`.` to move the selected segment. The `status` segment shows `Working` during agent execution, `Waiting` while Pi tools run, and `Ready` when the agent settles. Colors, icons, literal text, and other options remain JSON-only. Nerd Font detection can be overridden with `FOOTER_NERD_FONTS=1` or `FOOTER_NERD_FONTS=0`.
 
 ## Extension features
 
@@ -33,7 +33,7 @@ The third row is populated after the first completed turn. Its session and perfo
 - **Token and cost tracking**: total, cache, input/output, and accumulated cost segments
 - **Codex subscription quota**: optional exact 5-hour and weekly ChatGPT Codex usage percentages with reset countdowns and stale-snapshot fallback
 - **OpenRouter key-limit usage**: optional per-key paid-usage amount, limit, and percentage with stale-snapshot fallback
-- **Session statistics**: prompt, API-call, and model tool-call counts
+- **Session statistics**: prompt, API-call, model tool-call, and compaction counts
 - **Performance statistics**: cumulative LLM/tool duration, most recent user-prompt-to-completion turnaround time, average time to first token, output rate, and cache-hit percentage
 - **Thinking, mode, and status indicators**: thinking-level colors plus caveman, plan, chat, unified mode, and `Working`/`Waiting`/`Ready` status segments
 - **Nerd Font support**: automatic detection with plain-icon fallbacks
@@ -45,6 +45,10 @@ Create `~/.pi/agent/configs/opl-footer.json` or copy the tracked example from [`
 
 The config is cached for five seconds. Changes normally appear automatically; use `/reload` or restart Pi if needed.
 
+### Layout cost
+
+A row whose segments are all disabled renders nothing: the line and its divider are dropped, so a one-row layout costs two lines (a leading blank plus the row) and a three-row layout still costs six. A segment that throws during render shows `[?]` in its own cell instead of blanking the whole footer, and an unexpected session entry (a message without a `usage` block, for example) reads as zero rather than taking the rows with it. Branch-derived counters and the context estimate are cached by session, leaf, branch length, context window and whether usage needs estimating. Tree navigation and compaction invalidate the cache; equal-length branches refresh their values and canonical usage removes the estimate marker. Unchanged renders reuse the cached facts.
+
 ### Git probing
 
 The `git` segment reads branch (500 ms cache) and dirty counts (1 s cache) so an idle footer never spawns more than a couple of `git` processes per second. Two guards keep that floor honest:
@@ -52,30 +56,50 @@ The `git` segment reads branch (500 ms cache) and dirty counts (1 s cache) so an
 - The probes are skipped entirely when no configured row contains `git`, so a layout without the segment pays nothing for it.
 - In a directory that is not a repository, the first failed probe arms a 30 second back-off instead of re-running `git` every second forever. A mid-session `git init` or `git clone` clears it immediately (matched on tool results), as does any `write`/`edit` invalidation; a probe that fails inside a real repository (for example a locked index) is confirmed with `git rev-parse --is-inside-work-tree` and keeps the normal one-second cadence. A probe that finishes after an invalidation is dropped outright, so the failure that happened *before* a `git init` cannot push the fresh repository back into a 30 second back-off.
 
+Probes are also hardened against the repository itself. A worktree can declare programs - `[diff "x"] textconv`, `core.fsmonitor`, `core.hooksPath`, or a system or user config naming a helper - that git executes while answering what looks like a read-only query, so every call goes through a guard: `--no-pager`, `-c core.fsmonitor=false`, `-c core.hooksPath=`, `-c protocol.ext.allow=never`, `-c credential.helper=`, `GIT_CONFIG_NOSYSTEM`, `GIT_ATTR_NOSYSTEM`, `GIT_TERMINAL_PROMPT=0` and `GIT_OPTIONAL_LOCKS=0`, plus `--no-ext-diff --no-textconv` on diff-family subcommands. The probes only ever ask for branch names and porcelain status, and the guard block is duplicated from `opl-init` because installs are per-directory; `tests/net-guard-parity.test.mjs` fails if the two copies drift.
 ```json
 {
   "row1LeftSegments": ["pi", "separator", "model", "separator", "path", "git"],
   "row1RightSegments": ["context_pct"],
-  "row2LeftSegments": ["thinking", "separator", "mode_switcher"],
+  "row2LeftSegments": ["thinking", "separator", "caveman", "separator", "mode_switcher"],
   "row2RightSegments": ["token_total", "separator", "cost"],
   "row3LeftSegments": ["session_stats"],
   "row3RightSegments": ["perf_stats"]
 }
 ```
 
+That is the shipped default layout (`DEFAULT_CONFIG` in `config.ts`); `codex_usage` and `openrouter_usage` start disabled and are added by editing the arrays or using `/configurator`.
+
 See the tracked [`configs/opl-footer.json.sample`](../../configs/opl-footer.json.sample) for a complete example. Segment IDs, color fields, context-bar options, thinking-level colors, and icon overrides are documented below. Colors accept Pi theme tokens, six-digit hex, or the three-digit `#abc` shorthand (expanded to `#aabbcc`); the context bar gradient resolves both forms to RGB. An unknown token or malformed hex renders that text uncolored instead of failing the footer render, so a typo in `colors` or in `opl-modes`' `appearance.modeColor` costs you a color, not the footer.
 
 ## Architecture
 
 `index.ts` installs the footer and lifecycle tracking. `segments/` renders configurable values; `theme.ts`, `types.ts`, and `config.ts` provide styling and JSON configuration; session and performance statistics are collected in process memory and reconstructed from session history where possible.
 
+## Cross-extension seams
+
+While a footer is mounted, `opl-footer` publishes `__footerRequestRender` so another
+extension (`opl-modes`) can ask for a re-render outside a turn, and it reads `__agentMode`,
+`__planMode`, `__chatMode` and `__caveman` for the `mode_switcher`, `plan_mode`, `chat_mode`
+and `caveman` segments. Both sides are optional at install time, so the reads are validated rather than trusted:
+only a `{ mode: <non-empty string> }` is honoured, a malformed or missing value renders
+`Mode: Normal`, and a `modeColor` that is not a string is ignored.
+`session_shutdown` deletes the published trigger, because it closes over this session's TUI
+and a stale one would hand a dead component to the next session.
+
+For configuration, `opl-footer` publishes one entry on `globalThis.__oplConfiguratorTabs`
+(id `opl-footer`, hotkey `f`, label `Footer`) whose factory returns the same
+settings/reorder screen. The `/configurator` shell in `opl-configurator` owns the command
+and reads that array lazily; the entry is registered once at load and the factory is called
+fresh on every `/configurator` invocation.
+
 ## Available Segments
 
 | Segment | Description | Notes |
 |---------|-------------|-------|
 | `pi` | π symbol in accent blue | `pi` icon can be modified in config file |
 | `model` | Model name in pink + `(provider)` in dim | No icon; provider omitted if unavailable |
-| `path` | Current working directory | `segmentOptions.path.mode`: `"full"` (default) · `"abbreviated"` · `"basename"` |
+| `path` | Session directory (`ExtensionContext.cwd`), not the directory the harness was launched from | `segmentOptions.path.mode`: `"full"` (default) · `"abbreviated"` · `"basename"` |
 | `git` | Git branch and dirty indicators | `showBranch`, `showStaged`, `showUnstaged`, `showUntracked` (all bool) |
 | `context_pct` | Gradient bar + `X.X%` + max tokens | Bar fully configurable via `segmentOptions.contextBar` (see below). % and max tokens use `contextLabel` colour. Max tokens formatted with K/M suffix (e.g. `128k`, `2M`). Usage comes from `ctx.getContextUsage()`; when Pi reports it as unknown right after compaction, the segment estimates the rebuilt projection with Pi’s `estimateTokens()` and marks the bar and values with `≈` until a fresh assistant response provides exact usage. If no projection is available, it renders `(--%)` rather than a stale value. Set `DEBUG_PCT` in `context.ts` to a number (0–100) to pin the bar at a fixed value for visual testing. |
 | `cost` | `$<amount>` (4 decimals, e.g. `$0.0123`) | `$` dim, amount in `cost` colour (`muted` by default). Four decimals keep cheap local or short sessions distinguishable instead of pinning at `$0.00`. Shows dim `(no pricing)` when the session total is zero on a non-local model (provider has no pricing configured), and `(local model)` for local models |
@@ -91,6 +115,7 @@ See the tracked [`configs/opl-footer.json.sample`](../../configs/opl-footer.json
 | `cache_write` | Cache write tokens (hidden if zero) | — |
 | `context_total` | Total context window size | — |
 | `session_stats` | Prompt, API-call, and tool-call counts | Hidden until the first prompt |
+| `compactions` | Manual and automatic compaction count from the active session branch, including resumed-session history | Nerd Font zip-box icon or 📦 fallback; hidden at zero |
 | `perf_stats` | LLM/tool timing, TTFT, output rate, and cache-hit percentage | Hidden until the first prompt |
 | `status` | `Working`, `Waiting`, or `Ready` | `accent`, `warning`, and `success` theme colors respectively; optional and hidden by default |
 | `codex_usage` | `5h 76% ↻2h18m · W 37% ↻3d7h` | Exact remaining ChatGPT Codex subscription quota; OAuth-only, optional and hidden by default; a retained snapshot is marked `(stale)` after refresh failure |
@@ -100,13 +125,13 @@ See the tracked [`configs/opl-footer.json.sample`](../../configs/opl-footer.json
 
 ## Codex Subscription Usage
 
-Add `codex_usage` to any row through `/configure-opl` or `opl-footer.json`. While the active model is the OAuth-authenticated `openai-codex` provider, the footer asks Pi's model registry to resolve the same short-lived OAuth access token that Pi uses for the selected model, then sends `GET https://chatgpt.com/backend-api/wham/usage` directly from the local Pi process. The request carries `Authorization: Bearer <Pi OAuth token>`, `Accept: application/json`, a fixed `User-Agent: opl-footer-codex-usage`, and the token's `chatgpt_account_id` JWT claim as `chatgpt-account-id` when present. It refreshes after session start, model selection, each completed assistant response, each tool completion, and settled agent runs. Refreshes are non-blocking, with a 30-second floor and a 15-second request timeout; events within that floor coalesce into one trailing refresh, including events received during an in-flight request. Pending refreshes are cancelled on session reset, shutdown, or switching away from Codex, and recheck whether the segment is enabled before fetching. It classifies the returned windows by duration rather than response order. This is ChatGPT subscription quota, not OpenAI Platform API-key usage or billing.
+Add `codex_usage` to any row through `/configurator` or `opl-footer.json`. While the active model is the OAuth-authenticated `openai-codex` provider, the footer asks Pi's model registry to resolve the same short-lived OAuth access token that Pi uses for the selected model, then sends `GET https://chatgpt.com/backend-api/wham/usage` directly from the local Pi process. The request carries `Authorization: Bearer <Pi OAuth token>`, `Accept: application/json`, a fixed `User-Agent: opl-footer-codex-usage`, and the token's `chatgpt_account_id` JWT claim as `chatgpt-account-id` when present. It refreshes after session start, model selection, each completed assistant response, each tool completion, and settled agent runs. Refreshes are non-blocking, with a 30-second floor and a 15-second request timeout; events within that floor coalesce into one trailing refresh, including events received during an in-flight request. Pending refreshes are cancelled on session reset, shutdown, or switching away from Codex, and recheck whether the segment is enabled before fetching. It classifies the returned windows by duration rather than response order. This is ChatGPT subscription quota, not OpenAI Platform API-key usage or billing.
 
 No OAuth token, account ID, or response body is written to disk, logged, added to the Pi session, or sent anywhere other than `chatgpt.com` for that request. **The footer retains only the parsed 5-hour/weekly percentage and reset time in process memory for the active session.** The endpoint is an internal ChatGPT backend API and can change without notice. A failed refresh keeps the most recent exact snapshot and marks it `(stale)`; if no request has ever succeeded, the segment stays hidden. Disabling the segment prevents future requests and discards any result from a request already in flight.
 
 ## OpenRouter Usage
 
-Add `openrouter_usage` to any row through `/configure-opl` or `opl-footer.json`. While the selected model provider is `openrouter`, the footer resolves the same API key Pi uses for inference and sends `GET https://openrouter.ai/api/v1/key` from the local Pi process. It renders the configured per-key limit as `$<limit - limit_remaining> / $<limit> (<percent>%)`; an absent, malformed, or unlimited key cap leaves the segment hidden. The numerator deliberately uses OpenRouter's authoritative `limit_remaining`, rather than `usage` or `byok_usage`, because those ledgers may not both count against the key limit.
+Add `openrouter_usage` to any row through `/configurator` or `opl-footer.json`. While the selected model provider is `openrouter`, the footer resolves the same API key Pi uses for inference and sends `GET https://openrouter.ai/api/v1/key` from the local Pi process. It renders the configured per-key limit as `$<limit - limit_remaining> / $<limit> (<percent>%)`; an absent, malformed, or unlimited key cap leaves the segment hidden. The numerator deliberately uses OpenRouter's authoritative `limit_remaining`, rather than `usage` or `byok_usage`, because those ledgers may not both count against the key limit.
 
 It refreshes after session start, model selection, each completed assistant response, each tool completion, and settled agent runs. Refreshes are non-blocking, with a 30-second floor and a 15-second request timeout; events within that floor coalesce into one trailing refresh, including events received during an in-flight request. Pending refreshes are cancelled on session reset, shutdown, or switching away from OpenRouter, and recheck whether the segment is enabled before fetching. No API key or response body is written to disk, logged, added to the Pi session, or sent anywhere other than `openrouter.ai`. A failed refresh keeps the most recent exact snapshot and marks it `(stale)`; if no request has ever succeeded, the segment stays hidden. Disabling the segment prevents future requests and discards any result from a request already in flight.
 

package/extensions/opl-footer/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { FooterUserConfig, StatusLineSegmentId, ColorScheme, StatusLineSegmentOptions } from "./types.js";
 import { getDefaultColors } from "./theme.js";
 import type { IconSet } from "./icons.js";
@@ -27,7 +28,7 @@ export const CONFIGURABLE_SEGMENTS: StatusLineSegmentId[] = [
   "pi", "model", "path", "git", "thinking", "caveman", "plan_mode",
   "chat_mode", "mode_switcher", "token_in", "token_out", "token_total",
   "cache_read", "cache_write", "cost", "context_pct", "context_total",
-  "session_stats", "perf_stats", "status", "codex_usage", "openrouter_usage",
+  "session_stats", "compactions", "perf_stats", "status", "codex_usage", "openrouter_usage",
 ];
 
 const DEFAULT_LAYOUTS: Record<FooterLayoutKey, StatusLineSegmentId[]> = {
@@ -54,9 +55,9 @@ let userConfigCache: FooterUserConfig | null = null;
 let userConfigCacheTime = 0;
 const CACHE_TTL = 5000; // 5 seconds
 
-function getConfigPath(): string {
-  const homeDir = process.env.HOME || process.env.USERPROFILE || "";
-  return join(homeDir, ".pi", "agent", "configs", "opl-footer.json");
+/** Resolved per call so a custom `PI_AGENT_DIR` (pi's own agent dir) is honoured. */
+export function configPath(): string {
+  return join(getAgentDir(), "configs", "opl-footer.json");
 }
 
 export function loadUserConfig(): FooterUserConfig | null {
@@ -65,10 +66,10 @@ export function loadUserConfig(): FooterUserConfig | null {
     return userConfigCache;
   }
 
-  const configPath = getConfigPath();
+  const file = configPath();
   try {
-    if (existsSync(configPath)) {
-      const content = readFileSync(configPath, "utf-8");
+    if (existsSync(file)) {
+      const content = readFileSync(file, "utf-8");
       const parsed = JSON.parse(content);
       userConfigCache = parsed as FooterUserConfig;
       userConfigCacheTime = now;
@@ -178,9 +179,9 @@ export function setSegmentSeparator(
 }
 
 export function saveUserConfig(config: FooterUserConfig): void {
-  const configPath = getConfigPath();
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+  const file = configPath();
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(config, null, 2) + "\n", "utf-8");
   clearUserConfigCache();
 }