@openlines/opl-pi-sht 0.1.14

package/configs/opl-webaccess.json.sample

@@ -0,0 +1,31 @@
+{
+  "provider": "searxng",
+  "providers": {
+    "gemini": {
+      "apiKeyEnv": "GEMINI_API_KEY",
+      "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
+      "model": "gemini-3.5-flash-lite",
+      "_available_models": ["gemini-3.6-flash", "gemini-3.5-flash-lite", "gemini-2.5-flash", "gemini-2.5-pro"]
+    },
+    "tavily": {
+      "apiKeyEnv": "TAVILY_API_KEY",
+      "maxResults": 5
+    },
+    "ddgs": {
+      "apiUrl": "http://192.168.1.100:8000",
+      "maxResults": 12
+    },
+    "searxng": {
+      "instanceUrl": "http://192.168.1.100:8888",
+      "maxResults": 12,
+      "categories": "general",
+      "safeSearch": 0
+    },
+    "exa": {
+      "apiKeyEnv": "EXA_API_KEY",
+      "maxResults": 5,
+      "searchType": "auto",
+      "includeSummary": true
+    }
+  }
+}

package/extensions/opl-browser/README.md

@@ -0,0 +1,83 @@
+# opl-browser
+
+Chromium browser automation for pi via [Playwright](https://playwright.dev). One
+LLM-callable dispatcher tool covers navigation, accessibility snapshots, element
+interaction, console/network capture, script evaluation, and screenshots —
+enough to replace the `chrome-devtools` MCP server without running a separate
+process.
+
+## Commands, flags, and shortcuts
+
+No slash commands. The extension registers a single tool, `browser`, chosen by an
+`action` parameter:
+
+```ts
+browser({ action: "navigate", url: "https://example.com" })
+browser({ action: "snapshot" })
+browser({ action: "click", selector: "button.login" })
+browser({ action: "fill", selector: "#email", text: "a@b.com" })
+browser({ action: "evaluate", script: "document.title" })
+browser({ action: "console" })
+browser({ action: "network" })
+browser({ action: "screenshot", path: "shot.png", fullPage: true })
+browser({ action: "get", responseId: "br-..." })   // retrieve a stored large result
+browser({ action: "close" })
+```
+
+Full action set: `navigate` (url, or `back`/`forward`/`reload`), `snapshot`,
+`screenshot`, `click`, `fill`, `hover`, `press`, `select`, `evaluate`, `console`,
+`network`, `wait_for`, `pages`, `new_page`, `select_page`, `close_page`, `resize`,
+`get`, `close`.
+
+## Extension features
+
+- **Single dispatcher tool.** One compact schema in the system prompt instead of
+  ~29 per-tool schemas. Keeps the cached prefix small.
+- **Handle + preview output.** Large results (snapshots, console/network logs,
+  evaluate output) are kept out of context: the tool returns a truncated preview
+  plus a `responseId`; call `action: "get"` with that id for the full text.
+  Screenshots are written to a file, never inlined as base64.
+- **Real Chromium via Playwright.** Navigation with `domcontentloaded` waits,
+  CSS-selector interaction, viewport control, multi-page management.
+- **Per-page capture.** Console messages and network requests are buffered per
+  page as they occur; `console` and `network` actions return the active page's
+  buffer.
+- **One reused browser per session.** Launched on first use, closed automatically
+  on `session_shutdown`, or on demand via `action: "close"`.
+
+## Configuration
+
+Optional `~/.pi/agent/configs/opl-browser.json` (see `opl-browser.json.sample`):
+
+| Field | Default | Meaning |
+|---|---|---|
+| `headless` | `true` | Run Chromium headless. Set `false` to watch. |
+| `width` / `height` | `1280` / `800` | Initial viewport. |
+| `navigationTimeoutMs` | `30000` | Default navigation and `wait_for` timeout. |
+| `previewChars` | `4000` | Inline threshold; larger outputs are stored and previewed. |
+
+### Dependencies
+
+Playwright is a real third-party dependency, so install it in the extension
+directory and download the Chromium binary once:
+
+```bash
+cd extensions/opl-browser
+npm install
+npx playwright install chromium
+```
+
+## Architecture
+
+```text
+index.ts     Pi wiring: registers the single `browser` tool, TTL result store,
+             preview/handle logic, and session_shutdown cleanup.
+browser.ts   Playwright driver: browser/context/page lifecycle, per-page console
+             and network buffers, and the action switch.
+config.ts    DEFAULT_CONFIG + loadUserConfig (user overrides win via ??).
+```
+
+Interaction is CSS-selector based. Snapshot-uid interaction (referencing elements
+by ids returned from `snapshot`) is intentionally not implemented; use CSS
+selectors, which are simpler and robust. The in-memory result store expires
+entries after one hour or when the browser is closed.

package/extensions/opl-browser/browser.ts

@@ -0,0 +1,185 @@
+import { chromium, type Browser, type BrowserContext, type Page, type ConsoleMessage } from "playwright";
+import type { BrowserConfig } from "./config.js";
+
+// ponytail: single module-level Chromium instance reused across tool calls.
+// One browser per session is enough; add contexts only if parallel isolation matters.
+let browser: Browser | null = null;
+let context: BrowserContext | null = null;
+let activeIndex = 0;
+
+const consoleBuf = new WeakMap<Page, string[]>();
+const networkBuf = new WeakMap<Page, string[]>();
+
+function track(page: Page, cfg: BrowserConfig): void {
+  consoleBuf.set(page, []);
+  networkBuf.set(page, []);
+  page.setDefaultNavigationTimeout(cfg.navigationTimeoutMs);
+  page.on("console", (m: ConsoleMessage) => consoleBuf.get(page)?.push(`[${m.type()}] ${m.text()}`));
+  page.on("requestfinished", async (req) => {
+    try {
+      const res = await req.response();
+      networkBuf.get(page)?.push(`${req.method()} ${res?.status() ?? "?"} ${req.url()}`);
+    } catch {
+      /* response unavailable */
+    }
+  });
+  page.on("requestfailed", (req) =>
+    networkBuf.get(page)?.push(`${req.method()} FAILED ${req.url()} (${req.failure()?.errorText ?? "unknown"})`),
+  );
+}
+
+async function ensure(cfg: BrowserConfig): Promise<BrowserContext> {
+  if (context) return context;
+  browser = await chromium.launch({ headless: cfg.headless });
+  context = await browser.newContext({ viewport: { width: cfg.width, height: cfg.height } });
+  const page = await context.newPage();
+  track(page, cfg);
+  activeIndex = 0;
+  return context;
+}
+
+function page(): Page {
+  const pages = context!.pages();
+  if (!pages.length) throw new Error("no open pages");
+  return pages[activeIndex] ?? pages[pages.length - 1];
+}
+
+export interface BrowserActionResult {
+  text: string;
+  file?: string;
+}
+
+export interface BrowserParams {
+  action: string;
+  url?: string;
+  selector?: string;
+  text?: string;
+  key?: string;
+  values?: string[];
+  script?: string;
+  path?: string;
+  index?: number;
+  fullPage?: boolean;
+  timeoutMs?: number;
+  width?: number;
+  height?: number;
+}
+
+export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<BrowserActionResult> {
+  if (p.action === "close") {
+    await closeBrowser();
+    return { text: "Browser closed." };
+  }
+
+  const ctx = await ensure(cfg);
+
+  switch (p.action) {
+    case "navigate": {
+      const url = p.url ?? "";
+      if (url === "back") { await page().goBack(); }
+      else if (url === "forward") { await page().goForward(); }
+      else if (url === "reload") { await page().reload(); }
+      else if (url) { await page().goto(url, { waitUntil: "domcontentloaded" }); }
+      else throw new Error("navigate requires url (or back|forward|reload)");
+      return { text: `${page().url()} — ${await page().title()}` };
+    }
+    case "snapshot": {
+      const tree = await page().locator("body").ariaSnapshot();
+      return { text: tree || "(empty snapshot)" };
+    }
+    case "screenshot": {
+      const file = p.path ?? `opl-browser-${Date.now()}.png`;
+      await page().screenshot({ path: file, fullPage: p.fullPage ?? false });
+      return { text: `Screenshot saved to ${file}`, file };
+    }
+    case "click": {
+      if (!p.selector) throw new Error("click requires selector");
+      await page().click(p.selector);
+      return { text: `Clicked ${p.selector}` };
+    }
+    case "fill": {
+      if (!p.selector || p.text == null) throw new Error("fill requires selector and text");
+      await page().fill(p.selector, p.text);
+      return { text: `Filled ${p.selector}` };
+    }
+    case "hover": {
+      if (!p.selector) throw new Error("hover requires selector");
+      await page().hover(p.selector);
+      return { text: `Hovered ${p.selector}` };
+    }
+    case "press": {
+      if (!p.key) throw new Error("press requires key");
+      await page().keyboard.press(p.key);
+      return { text: `Pressed ${p.key}` };
+    }
+    case "select": {
+      if (!p.selector || !p.values?.length) throw new Error("select requires selector and values");
+      const picked = await page().selectOption(p.selector, p.values);
+      return { text: `Selected ${picked.join(", ")} in ${p.selector}` };
+    }
+    case "evaluate": {
+      if (!p.script) throw new Error("evaluate requires script");
+      const value = await page().evaluate(p.script);
+      return { text: typeof value === "string" ? value : JSON.stringify(value, null, 2) };
+    }
+    case "console": {
+      const msgs = consoleBuf.get(page()) ?? [];
+      return { text: msgs.length ? msgs.join("\n") : "(no console messages)" };
+    }
+    case "network": {
+      const reqs = networkBuf.get(page()) ?? [];
+      return { text: reqs.length ? reqs.join("\n") : "(no network requests)" };
+    }
+    case "wait_for": {
+      const timeout = p.timeoutMs ?? cfg.navigationTimeoutMs;
+      if (p.selector) await page().waitForSelector(p.selector, { timeout });
+      else if (p.text) await page().getByText(p.text).first().waitFor({ timeout });
+      else throw new Error("wait_for requires selector or text");
+      return { text: `Condition met` };
+    }
+    case "pages": {
+      const list = ctx.pages().map((pg, i) => `${i === activeIndex ? "*" : " "} [${i}] ${pg.url()}`);
+      return { text: list.join("\n") || "(no pages)" };
+    }
+    case "new_page": {
+      const pg = await ctx.newPage();
+      track(pg, cfg);
+      activeIndex = ctx.pages().length - 1;
+      if (p.url) await pg.goto(p.url, { waitUntil: "domcontentloaded" });
+      return { text: `Opened page [${activeIndex}] ${pg.url()}` };
+    }
+    case "select_page": {
+      const i = p.index ?? 0;
+      if (i < 0 || i >= ctx.pages().length) throw new Error(`no page at index ${i}`);
+      activeIndex = i;
+      return { text: `Selected page [${i}] ${page().url()}` };
+    }
+    case "close_page": {
+      const i = p.index ?? activeIndex;
+      const pages = ctx.pages();
+      if (i < 0 || i >= pages.length) throw new Error(`no page at index ${i}`);
+      await pages[i].close();
+      activeIndex = Math.max(0, ctx.pages().length - 1);
+      return { text: `Closed page [${i}]` };
+    }
+    case "resize": {
+      if (p.width == null || p.height == null) throw new Error("resize requires width and height");
+      await page().setViewportSize({ width: p.width, height: p.height });
+      return { text: `Resized to ${p.width}x${p.height}` };
+    }
+    default:
+      throw new Error(`unknown action: ${p.action}`);
+  }
+}
+
+export async function closeBrowser(): Promise<void> {
+  try {
+    await context?.close();
+    await browser?.close();
+  } catch {
+    /* already gone */
+  }
+  context = null;
+  browser = null;
+  activeIndex = 0;
+}

package/extensions/opl-browser/config.ts

@@ -0,0 +1,37 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface BrowserConfig {
+  headless: boolean;
+  width: number;
+  height: number;
+  navigationTimeoutMs: number;
+  previewChars: number;
+}
+
+export const DEFAULT_CONFIG: BrowserConfig = {
+  headless: true,
+  width: 1280,
+  height: 800,
+  navigationTimeoutMs: 30000,
+  previewChars: 4000,
+};
+
+const CONFIG_PATH = path.join(os.homedir(), ".pi", "agent", "configs", "opl-browser.json");
+
+export function loadUserConfig(configPath = CONFIG_PATH): BrowserConfig {
+  let user: Partial<BrowserConfig> = {};
+  try {
+    user = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    user = {};
+  }
+  return {
+    headless: user.headless ?? DEFAULT_CONFIG.headless,
+    width: user.width ?? DEFAULT_CONFIG.width,
+    height: user.height ?? DEFAULT_CONFIG.height,
+    navigationTimeoutMs: user.navigationTimeoutMs ?? DEFAULT_CONFIG.navigationTimeoutMs,
+    previewChars: user.previewChars ?? DEFAULT_CONFIG.previewChars,
+  };
+}

package/extensions/opl-browser/index.ts

@@ -0,0 +1,89 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import { loadUserConfig } from "./config.js";
+import { runAction, closeBrowser, type BrowserParams } from "./browser.js";
+
+// ponytail: in-memory store with 1h TTL. Large outputs (snapshot, console,
+// network, evaluate) are kept out of context; only a preview + id are returned.
+interface Stored { id: string; action: string; timestamp: number; text: string }
+const STORE = new Map<string, Stored>();
+const TTL_MS = 60 * 60 * 1000;
+
+function store(action: string, text: string): string {
+  const id = `br-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const now = Date.now();
+  for (const [k, v] of STORE) if (now - v.timestamp > TTL_MS) STORE.delete(k);
+  STORE.set(id, { id, action, timestamp: now, text });
+  return id;
+}
+
+const ACTIONS =
+  "navigate|snapshot|screenshot|click|fill|hover|press|select|evaluate|console|network|wait_for|pages|new_page|select_page|close_page|resize|get|close";
+
+export default function (pi: ExtensionAPI) {
+  const cfg = loadUserConfig();
+
+  pi.on("session_shutdown", async () => {
+    await closeBrowser();
+  });
+
+  pi.registerTool({
+    name: "browser",
+    label: "Browser",
+    description:
+      `Drive a real Chromium browser (Playwright) for web testing and inspection. One dispatcher tool; pick action: ${ACTIONS}. ` +
+      "navigate(url|back|forward|reload); snapshot (accessibility tree); screenshot (saved to file, not inlined); " +
+      "click/fill/hover/select by CSS selector; press(key); evaluate(script in page); console/network (captured for active page); " +
+      "wait_for(selector|text); pages/new_page/select_page/close_page; resize(width,height); get(responseId) to retrieve a stored large result; close to shut the browser. " +
+      "Large outputs return a preview + responseId; call action:get with that id for the full text.",
+    parameters: Type.Object({
+      action: Type.String({ description: `One of: ${ACTIONS}` }),
+      url: Type.Optional(Type.String({ description: "navigate/new_page: URL, or back|forward|reload for navigate" })),
+      selector: Type.Optional(Type.String({ description: "CSS selector for click/fill/hover/select/wait_for" })),
+      text: Type.Optional(Type.String({ description: "fill: text to type; wait_for: text to await" })),
+      key: Type.Optional(Type.String({ description: "press: key or combo, e.g. Enter, Control+A" })),
+      values: Type.Optional(Type.Array(Type.String(), { description: "select: option values" })),
+      script: Type.Optional(Type.String({ description: "evaluate: JS expression run in the page" })),
+      path: Type.Optional(Type.String({ description: "screenshot: output file path" })),
+      fullPage: Type.Optional(Type.Boolean({ description: "screenshot: capture full scrollable page" })),
+      index: Type.Optional(Type.Number({ description: "select_page/close_page: page index" })),
+      timeoutMs: Type.Optional(Type.Number({ description: "wait_for: timeout in ms" })),
+      width: Type.Optional(Type.Number({ description: "resize: viewport width" })),
+      height: Type.Optional(Type.Number({ description: "resize: viewport height" })),
+      responseId: Type.Optional(Type.String({ description: "get: id from a previous large result" })),
+    }),
+    async execute(_toolCallId, params) {
+      const p = params as BrowserParams & { responseId?: string };
+
+      if (p.action === "get") {
+        if (!p.responseId) return err("get requires responseId");
+        const hit = STORE.get(p.responseId);
+        if (!hit) return err(`No stored result for ${p.responseId} (expires after 1h or on browser close).`);
+        return { content: [{ type: "text", text: hit.text }], details: { responseId: hit.id, action: hit.action } };
+      }
+
+      let result;
+      try {
+        result = await runAction(p, cfg);
+      } catch (e) {
+        return err(`browser ${p.action}: ${e instanceof Error ? e.message : String(e)}`);
+      }
+
+      // Small outputs return inline; large outputs are stored and previewed.
+      if (result.text.length <= cfg.previewChars) {
+        return { content: [{ type: "text", text: result.text }], details: result.file ? { file: result.file } : {} };
+      }
+      const id = store(p.action, result.text);
+      const preview = result.text.slice(0, cfg.previewChars);
+      return {
+        content: [{ type: "text", text: `${preview}\n\n… truncated. Full result via action:get responseId: ${id}` }],
+        details: { responseId: id, action: p.action, chars: result.text.length },
+      };
+    },
+  });
+}
+
+function err(text: string) {
+  return { content: [{ type: "text" as const, text: `Error: ${text}` }], isError: true, details: {} as Record<string, unknown> };
+}

package/extensions/opl-browser/package-lock.json

@@ -0,0 +1,60 @@
+{
+  "name": "opl-browser",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "opl-browser",
+      "version": "1.0.0",
+      "license": "ISC",
+      "dependencies": {
+        "playwright": "^1.49.0"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.62.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.62.1.tgz",
+      "integrity": "sha512-0M+L3LAD8/nm554LOla9Ayx0j0tmFZ0FBcoQ7F1VuVHpM/XpiC8RcDzBQB8W5+hA8L22THxELzeF+2WcUzvcLg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.62.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.62.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.62.1.tgz",
+      "integrity": "sha512-wPYSwEBJY9GHraISXqyqtx0na0LpO3XEX7jNDhntbex7tzUS7kLnZsOlFruFJB4Hi/rhDMjXGqHewDZ68nYZVw==",
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    }
+  }
+}

package/extensions/opl-browser/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "opl-browser",
+  "version": "1.0.0",
+  "description": "Chromium browser automation for pi via Playwright. A single dispatcher tool for navigation, snapshots, interaction, console/network capture, and evaluation — replaces the chrome-devtools MCP server.",
+  "main": "index.js",
+  "license": "ISC",
+  "dependencies": {
+    "playwright": "^1.49.0"
+  }
+}

package/extensions/opl-ctxtrim/README.md

@@ -0,0 +1,78 @@
+# 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.
+
+## Commands, tools, and configuration
+
+No commands, tools, or configuration. Loading the extension is the entire interface.
+
+## 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.
+
+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:
+
+- OpenAI Responses / Anthropic / Google: `{ name, description, parameters }`
+- OpenAI Chat Completions / Mistral: `{ function: { name, description, parameters } }`
+- Amazon Bedrock Converse: `toolConfig.tools[].toolSpec`
+
+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.
+
+## 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:
+
+| Schema state | Bytes | Change from original |
+|---|---:|---:|
+| Original context-mode tools | 28,019 | — |
+| 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.
+
+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.
+
+### Observed provider accounting
+
+Fresh `/init` sessions on `litellm-proxy/gpt-5.6-terra` supplied a more useful real-world check. `cacheWrite` is the provider-reported initial cached prompt prefix; `input: 2` is only the small uncached request tail.
+
+| Configuration | Repository | `cacheWrite` | Cache-write cost |
+|---|---|---:|---:|
+| ctxtrim off, Ponytail full | piper-tts-reader | 22,148 | $0.060907 |
+| ctxtrim off, Ponytail full | openpi-memory | 22,229 | $0.061130 |
+| ctxtrim on, Ponytail full | opl-pi-sht | 19,822 | $0.054511 |
+| ctxtrim on, Ponytail off | openpi-memory | **16,774** | **$0.046129** |
+
+The two untrimmed repositories were within 81 tokens (0.37%), despite different crawls. The observations indicate:
+
+- `opl-ctxtrim` reduced a fresh initial request by about **2.3k provider-accounted tokens (10.5-10.8%)**. This comparison spans different repositories, so it is indicative rather than laboratory-controlled.
+- With ctxtrim enabled, turning Ponytail full mode off removed another **3,048 tokens (15.4%)** in the available cross-repository comparison.
+- In the same `openpi-memory` repository, moving from ctxtrim off/Ponytail full to ctxtrim on/Ponytail off saved **5,455 tokens (24.5%)** and **$0.015001** on the initial cache write. This is the combined effect, not an attribution split.
+
+Savings apply to every provider request that carries the tool schema, including tool-follow-up turns. Exact token counts and costs vary by provider tokenizer, cache policy, repository crawl, loaded context files, system prompts, and skills.
+
+### Other initial-prompt overhead
+
+`opl-ctxtrim` only trims known context-mode tool-schema descriptions. It does not remove context-mode's routing anchor, active-memory injection, tool results, indexed search results, Pi's base prompt, project guides, or skills.
+
+In the local setup used for the observations above:
+
+- Ponytail full mode appended **5,252 bytes / 876 words** on every `before_agent_start`; disabling it produced the measured 3,048-token additional reduction above. `lite` is 5,225 bytes, so it is not a meaningful token-saving mode.
+- Pi's Superpowers catalog contributed 14 names/descriptions totaling **2,168 bytes**. Its full 138.6 KB of skill instructions is loaded on demand, not in the initial prompt.
+- The project `AGENTS.md` guide was **4,270 bytes / 500 words**. It is useful repository context, but shortening it is a quality tradeoff.
+- `opl-modes` injects only the active mode's prompt. Its default and this measured session were `off`, so its configured chat, plan, review, and research prompts added nothing.
+
+Removing or lazily exposing entire `ctx_*` tools could save more than description trimming, but makes those tools unavailable to the model. The extension intentionally preserves the complete tool set and all JSON Schema semantics.
+
+## Architecture
+
+```text
+index.ts   before_provider_request handler; CTX_DESCRIPTIONS map;
+           provider-shape detection; description-only trimming.
+```
+
+Exports `trimPayload`, `CTX_DESCRIPTIONS`, and `shortenParamDescription` for testing. The extension is self-contained and dependency-free.