@openlines/opl-pi-sht 0.2.4 → 0.2.6

package/README.md

@@ -17,7 +17,7 @@ A portable collection of various Pi coding agent extensions. Repository director
 <div align="center">
 
 >
-> ## v0.2.4 (22 Sept 2026) - Pi 0.87 host-loader smoke test now runs in CI<br/>see [CHANGELOG.md](CHANGELOG.md) for more details.
+> ### v0.2.6 (24 Sept 2026) - **Post-compaction context estimate**: `opl-footer` keeps the context bar visible with explicitly approximate values until Pi reports fresh usage. <br/>see [CHANGELOG.md](CHANGELOG.md) for more details.
 >
 
 </div>

package/configs/opl-browser.json.sample

@@ -4,5 +4,6 @@
   "width": 1280,
   "height": 800,
   "navigationTimeoutMs": 30000,
-  "previewChars": 4000
+  "previewChars": 4000,
+  "getChars": 30000
 }

package/configs/opl-webaccess.json.sample

@@ -1,4 +1,7 @@
 {
+  "_comment_limits": "Optional top-level caps: maxContentChars caps the initial web_search/fetch_content body (default 30000); maxRetrievalChars caps one get_search_content page (default 30000). Pass offset=N to get_search_content to continue a truncated retrieval.",
+  "maxContentChars": 30000,
+  "maxRetrievalChars": 30000,
   "provider": "searxng",
   "providers": {
     "gemini": {

package/extensions/opl-browser/README.md

@@ -37,8 +37,9 @@ Full action set: `navigate` (url, or `back`/`forward`/`reload`), `snapshot`,
   ~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.
+  plus a `responseId`; call `action: "get"` with that id to page through the full
+  text (`getChars` per page, pass `offset` to continue). Screenshots are written to
+  a file, never inlined as base64.
 - **Structured extraction.** `extract` runs Readability + Turndown over the
   *rendered* (post-JS) DOM — the complement to `opl-webaccess`'s `fetch_content`,
   which only sees raw HTTP HTML. Static pages: `fetch_content`; rendered or
@@ -66,6 +67,7 @@ Optional `~/.pi/agent/configs/opl-browser.json` (see `opl-browser.json.sample`):
 | `width` / `height` | `1280` / `800` | Initial viewport. |
 | `navigationTimeoutMs` | `30000` | Default navigation and `wait_for` timeout. |
 | `previewChars` | `4000` | Inline threshold; larger outputs are stored and previewed. |
+| `getChars` | `30000` | Characters returned by one `action: "get"` page. |
 
 ### Dependencies
 
@@ -87,6 +89,7 @@ browser.ts   Playwright driver: browser/context/page lifecycle, per-page console
              and network buffers, and the action switch.
 validate.ts  URL/path guards: http/https-only navigation, screenshot path confined
              to the project directory.
+paging.ts    Bounded `get` pagination and continuation metadata.
 extract.ts   Pure rendered-HTML → markdown pipeline (linkedom + Readability +
              turndown), duplicated from opl-webaccess to keep installs independent.
 config.ts    DEFAULT_CONFIG + loadUserConfig (user overrides win via ??).

package/extensions/opl-browser/config.ts

@@ -8,6 +8,7 @@ export interface BrowserConfig {
   height: number;
   navigationTimeoutMs: number;
   previewChars: number;
+  getChars: number;
 }
 
 export const DEFAULT_CONFIG: BrowserConfig = {
@@ -16,6 +17,7 @@ export const DEFAULT_CONFIG: BrowserConfig = {
   height: 800,
   navigationTimeoutMs: 30000,
   previewChars: 4000,
+  getChars: 30000,
 };
 
 const CONFIG_PATH = path.join(os.homedir(), ".pi", "agent", "configs", "opl-browser.json");
@@ -33,5 +35,6 @@ export function loadUserConfig(configPath = CONFIG_PATH): BrowserConfig {
     height: user.height ?? DEFAULT_CONFIG.height,
     navigationTimeoutMs: user.navigationTimeoutMs ?? DEFAULT_CONFIG.navigationTimeoutMs,
     previewChars: user.previewChars ?? DEFAULT_CONFIG.previewChars,
+    getChars: user.getChars ?? DEFAULT_CONFIG.getChars,
   };
 }

package/extensions/opl-browser/index.ts

@@ -3,6 +3,7 @@ import { Type } from "typebox";
 
 import { loadUserConfig } from "./config.js";
 import { runAction, closeBrowser, type BrowserParams } from "./browser.js";
+import { paginateStored, continuationNotice } from "./paging.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.
@@ -52,15 +53,20 @@ export default function (pi: ExtensionAPI) {
       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" })),
+      offset: Type.Optional(Type.Number({ description: "get: character offset to continue a truncated retrieval" })),
     }),
     async execute(_toolCallId, params) {
-      const p = params as BrowserParams & { responseId?: string };
+      const p = params as BrowserParams & { responseId?: string; offset?: number };
 
       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 } };
+        const page = paginateStored(hit.text, p.offset ?? 0, cfg.getChars);
+        return {
+          content: [{ type: "text", text: page.text + continuationNotice(page) }],
+          details: { responseId: hit.id, action: hit.action, chars: hit.text.length, offset: page.offset },
+        };
       }
 
       let result;

package/extensions/opl-browser/paging.ts

@@ -0,0 +1,26 @@
+export interface StoredPage {
+  text: string;
+  offset: number;
+  totalChars: number;
+  nextOffset: number | null;
+}
+
+/** Slice stored browser output to one bounded page. Offsets past the end yield empty text. */
+export function paginateStored(text: string, offset: number, maxChars: number): StoredPage {
+  const totalChars = text.length;
+  const safeOffset = Number.isFinite(offset) ? Math.floor(offset) : 0;
+  const start = Math.min(Math.max(0, safeOffset), totalChars);
+  const end = Math.min(start + maxChars, totalChars);
+  return {
+    text: text.slice(start, end),
+    offset: start,
+    totalChars,
+    nextOffset: end < totalChars ? end : null,
+  };
+}
+
+/** Model-facing continuation metadata, empty when the page was complete. */
+export function continuationNotice(page: StoredPage): string {
+  if (page.nextOffset === null) return "";
+  return `\n\n[Content truncated at ${page.offset + page.text.length} of ${page.totalChars} chars. Continue with action:get offset=${page.nextOffset}.]`;
+}

package/extensions/opl-footer/README.md

@@ -75,7 +75,7 @@ See the tracked [`configs/opl-footer.json.sample`](../../configs/opl-footer.json
 | `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"` |
 | `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`). Set `DEBUG_PCT` in `context.ts` to a number (0–100) to pin the bar at a fixed value for visual testing. |
+| `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 |
 | `thinking` | `Thinking: <LEVEL>` | Dim label, CAPS level with per-level colour; always visible |
 | `mode_switcher` | Unified active mode label | Reads state published by `opl-modes`; `appearance.modeColor` controls the mode value, with hardcoded `muted` fallback |

package/extensions/opl-footer/git-status.ts

@@ -29,9 +29,16 @@ let branchInvalidationCounter = 0;
 let repoAbsentUntil = 0;
 let repoCheckInFlight = false;
 
+let clock: () => number = () => Date.now();
+
+/** Test seam: override the time source so TTL/back-off behaviour is deterministic. */
+export function setClock(fn?: () => number): void {
+  clock = fn ?? (() => Date.now());
+}
+
 /** Assume "not a repo" immediately, then confirm asynchronously so a real repo recovers. */
 function noteProbeFailure(): void {
-  repoAbsentUntil = Date.now() + NOT_A_REPO_TTL_MS;
+  repoAbsentUntil = clock() + NOT_A_REPO_TTL_MS;
   if (repoCheckInFlight) return;
   repoCheckInFlight = true;
   void runGit(["rev-parse", "--is-inside-work-tree"]).then((out) => {
@@ -41,7 +48,7 @@ function noteProbeFailure(): void {
 }
 
 function repoAbsent(): boolean {
-  return Date.now() < repoAbsentUntil;
+  return clock() < repoAbsentUntil;
 }
 
 function parseGitStatusOutput(output: string): { staged: number; unstaged: number; untracked: number } {
@@ -122,7 +129,7 @@ async function fetchGitStatus(): Promise<{ staged: number; unstaged: number; unt
 }
 
 export function getCurrentBranch(providerBranch: string | null): string | null {
-  const now = Date.now();
+  const now = clock();
 
   if (now < repoAbsentUntil) {
     return cachedBranch ? cachedBranch.branch : providerBranch;
@@ -141,7 +148,7 @@ export function getCurrentBranch(providerBranch: string | null): string | null {
         if (result === null) noteProbeFailure();
         cachedBranch = {
           branch: result,
-          timestamp: Date.now(),
+          timestamp: clock(),
         };
       }
       pendingBranchFetch = null;
@@ -152,7 +159,7 @@ export function getCurrentBranch(providerBranch: string | null): string | null {
 }
 
 export function getGitStatus(providerBranch: string | null): GitStatus {
-  const now = Date.now();
+  const now = clock();
 
   if (now < repoAbsentUntil) {
     const branch = cachedBranch ? cachedBranch.branch : providerBranch;
@@ -180,8 +187,8 @@ export function getGitStatus(providerBranch: string | null): GitStatus {
       if (fetchId === invalidationCounter) {
         if (result === null) noteProbeFailure();
         cachedStatus = result
-          ? { staged: result.staged, unstaged: result.unstaged, untracked: result.untracked, timestamp: Date.now() }
-          : { staged: 0, unstaged: 0, untracked: 0, timestamp: Date.now() };
+          ? { staged: result.staged, unstaged: result.unstaged, untracked: result.untracked, timestamp: clock() }
+          : { staged: 0, unstaged: 0, untracked: 0, timestamp: clock() };
       }
       pendingFetch = null;
     });

package/extensions/opl-footer/index.ts

@@ -5,6 +5,7 @@ import type { TUI } from "@earendil-works/pi-tui";
 
 import type { SegmentContext, StatusLineSegmentId, UsageStats, SessionStats, SessionEvent, ThinkingLevelEvent, AssistantMessageEvent, ToolResultEvent, UserBashEvent } from "./types.js";
 import { renderSegment } from "./segments/index.js";
+import { estimateContextUsage } from "./segments/context.js";
 import { createAgentStatusTracker } from "./segments/status.js";
 import { getGitStatus, invalidateGitStatus, invalidateGitBranch } from "./git-status.js";
 import { getEffectiveConfig } from "./config.js";
@@ -278,15 +279,16 @@ export default function footer(pi: ExtensionAPI) {
       ? thinkingEvents.reduce((_, e) => e.thinkingLevel ?? "off", "off")
       : null;
 
-    const lastAssistant = completedMessages.at(-1);
-
-    // Calculate context percentage
-    const contextTokens = lastAssistant
-      ? lastAssistant.usage.input + lastAssistant.usage.output +
-        lastAssistant.usage.cacheRead + lastAssistant.usage.cacheWrite
-      : 0;
-    const contextWindow = ctx.model?.contextWindow || 0;
-    const contextPercent = contextWindow > 0 ? (contextTokens / contextWindow) * 100 : 0;
+    // Prefer Pi's canonical context usage (0.87). Immediately after compaction it is
+    // null until the next assistant reply, so estimate the rebuilt projection instead.
+    const usage = typeof ctx.getContextUsage === "function" ? ctx.getContextUsage() : undefined;
+    const contextWindow = usage?.contextWindow ?? ctx.model?.contextWindow ?? 0;
+    const projectedMessages = ctx.sessionManager?.buildSessionProjection?.().messages;
+    const estimatedContextUsage = usage?.percent === null && contextWindow > 0 && projectedMessages
+      ? estimateContextUsage(projectedMessages, contextWindow)
+      : null;
+    const contextPercent = usage?.percent ?? estimatedContextUsage?.percent ?? null;
+    const contextEstimated = estimatedContextUsage !== null;
 
     // Get git status (cached). Skip the probes entirely when no visible row renders the
     // git segment — otherwise an unused cell keeps spawning git once per second.
@@ -325,6 +327,7 @@ export default function footer(pi: ExtensionAPI) {
       sessionId: ctx.sessionManager?.getSessionId?.(),
       usageStats,
       contextPercent,
+      contextEstimated,
       contextWindow,
       usingSubscription,
       sessionStartTime,

package/extensions/opl-footer/segments/context.ts

@@ -1,3 +1,5 @@
+import { estimateTokens } from "@earendil-works/pi-coding-agent";
+
 import type { RenderedSegment, SegmentContext } from "../types.js";
 import { applyColor, resolveColorToRgb } from "../theme.js";
 import { color } from "./helpers.js";
@@ -19,6 +21,14 @@ export function lerp(a: number, b: number, t: number): number {
   return Math.round(a + (b - a) * t);
 }
 
+export function estimateContextUsage(
+  messages: Parameters<typeof estimateTokens>[0][],
+  contextWindow: number,
+): { tokens: number; percent: number } {
+  const tokens = messages.reduce((total, message) => total + estimateTokens(message), 0);
+  return { tokens, percent: (tokens / contextWindow) * 100 };
+}
+
 function positionColor(
   pos: number,
   barWidth: number,
@@ -46,6 +56,9 @@ function positionColor(
 export const contextPctSegment = {
   id: "context_pct" as const,
   render(ctx: SegmentContext): RenderedSegment {
+    if (ctx.contextPercent === null) {
+      return { content: color(ctx, "contextLabel", "(--%)"), visible: true };
+    }
     const pct = DEBUG_PCT ?? ctx.contextPercent;
     const barOpts = ctx.options.contextBar ?? {};
 
@@ -72,7 +85,9 @@ export const contextPctSegment = {
 
     // Show: (00.00%) 99999 / 99999
     const used = Math.round((pct / 100) * ctx.contextWindow);
-    const pctLabel = `(${pct.toFixed(2)}%) ${formatTokens(used)} / ${formatTokens(ctx.contextWindow)}`;
+    const pctLabel = ctx.contextEstimated
+      ? `≈${pct.toFixed(2)}%  ≈${formatTokens(used)} / ${formatTokens(ctx.contextWindow)}`
+      : `(${pct.toFixed(2)}%) ${formatTokens(used)} / ${formatTokens(ctx.contextWindow)}`;
     const pctStr = color(ctx, "contextLabel", pctLabel);
 
     return { content: `${bar} ${pctStr}`, visible: true };

package/extensions/opl-footer/types.ts

@@ -118,7 +118,8 @@ export interface SegmentContext {
   thinkingLevel: string;
   sessionId: string | undefined;
   usageStats: UsageStats;
-  contextPercent: number;
+  contextPercent: number | null;
+  contextEstimated: boolean;
   contextWindow: number;
   usingSubscription: boolean;
   sessionStartTime: number;

package/extensions/opl-modes/README.md

@@ -11,7 +11,7 @@ Unified mode manager for Pi. It provides normal, read-only chat, read-only plann
 - `--chat` and `--plan` start Pi in the corresponding read-only mode.
 - The configured cycle shortcut rotates through enabled visible modes. Execute mode is excluded from cycling because it requires an active plan. The default `shift+tab` is also Pi's built-in `app.thinking.cycle`, so both fire on one press; rebind either action in `~/.pi/agent/keybindings.json` (or pick another `shortcuts.cycleMode`) if you want them separate.
 
-Plans are Markdown files under `.pi/plans/` with the `plan-` filename prefix. A plan name must contain at least one letter or digit, so `/plan .` or `/plan --` is rejected instead of producing an untitled `plan-.md`. `plan_complete` is available in execute mode and in any mode that sets `allowPlanComplete`. On completion, the plan file is deleted when `cleanup.cleanupOnComplete` is enabled. If execution ends without `plan_complete`, execute mode is exited automatically at Pi's `agent_before_settle` boundary (added in Pi 0.87.0) — but only when the run settled as `completed`: an aborted (ESC) or errored run keeps execute mode active so the plan can be resumed. On Pi < 0.87.0 this auto-exit is unavailable because the boundary is never emitted; `plan_complete` still exits the mode on any version.
+Plans are Markdown files under `.pi/plans/` with the `plan-` filename prefix. A plan name must contain at least one letter or digit, so `/plan .` or `/plan --` is rejected instead of producing an untitled `plan-.md`. Loading a plan appends a TUI-only card (via `registerEntryRenderer`) so the plan text never enters the model context; the execute-mode system prompt is the single model-facing copy of the plan. `plan_complete` is available in execute mode and in any mode that sets `allowPlanComplete`. On completion, the plan file is deleted when `cleanup.cleanupOnComplete` is enabled. If execution ends without `plan_complete`, execute mode is exited automatically at Pi's `agent_before_settle` boundary (added in Pi 0.87.0) — but only when the run settled as `completed`: an aborted (ESC) or errored run keeps execute mode active so the plan can be resumed. On Pi < 0.87.0 this auto-exit is unavailable because the boundary is never emitted; `plan_complete` still exits the mode on any version.
 
 ## Extension features
 

package/extensions/opl-modes/index.ts

@@ -853,23 +853,19 @@ export default function modeSwitcher(pi: ExtensionAPI) {
     const filePath = join(process.cwd(), PLAN_DIR, filename);
     if (existsSync(filePath)) {
       const planContent = readFileSync(filePath, "utf-8");
-      pi.sendMessage({
-        customType: "plan-mode",
-        content: planContent,
-        display: true,
-        details: { title: `Active plan: ${displayName}` },
-      });
+      pi.appendEntry("plan-mode", { title: displayName, plan: planContent });
     }
   }
 
-  // ─── Message renderer for plan messages ────────────────────────────────────
+  // ─── Entry renderer for TUI-only plan cards (never sent to the model) ──────
 
-  pi.registerMessageRenderer("plan-mode", (message, _options, theme) => {
+  pi.registerEntryRenderer("plan-mode", (entry, _options, theme) => {
+    const data = (entry.data ?? {}) as { title?: string; plan?: string };
     const border = new DynamicBorder((s: string) => theme.fg("border", s));
     const container = new Container();
     container.addChild(border);
-    container.addChild(new Text(theme.fg("text", "📄 " + (message.content as string).split("\n")[0])));
-    const body = (message.content as string).split("\n").slice(1).join("\n");
+    container.addChild(new Text(theme.fg("text", "📄 " + (data.title ?? ""))));
+    const body = (data.plan ?? "").split("\n").slice(1).join("\n");
     if (body) {
       container.addChild(new Spacer());
       container.addChild(new Text(body));

package/extensions/opl-webaccess/README.md

@@ -7,7 +7,7 @@ Provides configurable web search and readable URL/PDF retrieval with session-bac
 - Tools: `web_search`, `fetch_content`, and `get_search_content`.
 - `web_search` accepts `query` or parallel `queries`.
 - `fetch_content` accepts `url` or `urls` with at most three requests in flight.
-- `get_search_content` uses a prior `responseId`, with `queryIndex`, `urlIndex`, or exact `url` selection.
+- `get_search_content` uses a prior `responseId`, with `queryIndex`, `urlIndex`, or exact `url` selection. It returns one bounded page; pass `offset` to continue a truncated retrieval.
 - No slash commands or shortcuts.
 
 ## Extension features
@@ -15,7 +15,8 @@ Provides configurable web search and readable URL/PDF retrieval with session-bac
 - Searches through `gemini`, `tavily`, `ddgs`, `searxng`, or `exa`; multiple queries run concurrently and results include citations where available.
 - Extracts HTML with Readability and Markdown conversion, falls back to full-document Turndown conversion, passes PDF responses to the PDF extractor, and returns plain text, Markdown, and JSON directly.
 - Restricts `fetch_content` to http/https, caps each response at 10 MB, and applies a 30s timeout; Gemini keys are sent via the `x-goog-api-key` header rather than the query string.
-- Caps initial tool output at 30,000 characters, then keeps it for retrieval for one hour or until the session ends.
+- Caps initial tool output at a configurable length (default 30,000 characters), then keeps it for retrieval for one hour or until the session ends.
+- Pages `get_search_content` results (default 30,000 characters per page) with `offset` continuation, so a model never loads the whole stored body in one call.
 - Honors abort signals and returns provider, HTTP, and per-result failures through the tool boundary rather than throwing.
 
 ## Configuration
@@ -34,6 +35,13 @@ Copy [`configs/opl-webaccess.json.sample`](../../configs/opl-webaccess.json.samp
 
 Provider fields include `apiKeyEnv`, `apiUrl`, `baseUrl`, `model`, `maxResults`, `instanceUrl`, `categories`, `safeSearch`, `searchType`, and `includeSummary`. API keys are read only from named environment variables. Missing or invalid config falls back to Gemini defaults; an unknown provider returns an error.
 
+Optional top-level caps control how much content reaches the model:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `maxContentChars` | `30000` | Cap on the initial `web_search`/`fetch_content` body. |
+| `maxRetrievalChars` | `30000` | Cap on one `get_search_content` page. Pass `offset` to continue. |
+
 Install extraction dependencies before use:
 
 ```bash

package/extensions/opl-webaccess/config.ts

@@ -18,6 +18,21 @@ export interface ProviderConfig {
 export interface WebAccessConfig {
   provider: string;
   providers: Record<string, ProviderConfig>;
+  /** Cap on the initial web_search/fetch_content body (chars). */
+  maxContentChars?: number;
+  /** Cap on one get_search_content retrieval page (chars). */
+  maxRetrievalChars?: number;
+}
+
+export const DEFAULT_MAX_CONTENT_CHARS = 30_000;
+export const DEFAULT_MAX_RETRIEVAL_CHARS = 30_000;
+
+/** Resolve configurable content caps, falling back to defaults. */
+export function resolveCaps(cfg: Pick<WebAccessConfig, "maxContentChars" | "maxRetrievalChars">) {
+  return {
+    maxContentChars: cfg.maxContentChars ?? DEFAULT_MAX_CONTENT_CHARS,
+    maxRetrievalChars: cfg.maxRetrievalChars ?? DEFAULT_MAX_RETRIEVAL_CHARS,
+  };
 }
 
 const CONFIG_PATH = join(getAgentDir(), "configs", "opl-webaccess.json");

package/extensions/opl-webaccess/index.ts

@@ -8,12 +8,14 @@ import {
   getResult,
   persistResult,
   restoreFromSession,
-  MAX_CONTENT_CHARS,
 } from "./storage.js";
-import { truncate, errorMessage } from "./utils.js";
+import { truncate, errorMessage, paginateContent, continuationNotice } from "./utils.js";
+import { loadConfig, resolveCaps } from "./config.js";
 import type { StoredData } from "./types.js";
 
 export default function (pi: ExtensionAPI) {
+  const caps = resolveCaps(loadConfig());
+
   pi.on("session_start", async (_event, ctx) => {
     restoreFromSession(ctx);
   });
@@ -67,7 +69,7 @@ export default function (pi: ExtensionAPI) {
         return `## Query: "${r.query}"\n\n${r.answer}${sources}`;
       });
 
-      const body = truncate(sections.join("\n\n---\n\n"), MAX_CONTENT_CHARS);
+      const body = truncate(sections.join("\n\n---\n\n"), caps.maxContentChars);
       return {
         content: [{ type: "text", text: `${body}\n\n*responseId: ${id}*` }],
         details: { responseId: id, queryCount: results.length },
@@ -120,7 +122,7 @@ export default function (pi: ExtensionAPI) {
         return `## ${r.url}\n\n${title}${r.content}`;
       });
 
-      const body = truncate(sections.join("\n\n---\n\n"), MAX_CONTENT_CHARS);
+      const body = truncate(sections.join("\n\n---\n\n"), caps.maxContentChars);
       return {
         content: [{ type: "text", text: `${body}\n\n*responseId: ${id}*` }],
         details: { responseId: id, urlCount: results.length },
@@ -148,6 +150,9 @@ export default function (pi: ExtensionAPI) {
       url: Type.Optional(
         Type.String({ description: "Retrieve content for a specific URL (fetch_content)" })
       ),
+      offset: Type.Optional(
+        Type.Number({ description: "Character offset to continue a truncated retrieval" })
+      ),
     }),
     async execute(_toolCallId, params) {
       const data = getResult(params.responseId);
@@ -184,8 +189,13 @@ export default function (pi: ExtensionAPI) {
             ? "\n\n**Sources:**\n" +
               result.results.map((s, i) => `${i + 1}. [${s.title}](${s.url})`).join("\n")
             : "";
+        const page = paginateContent(
+          `## Query: "${result.query}"\n\n${result.answer}${sources}`,
+          params.offset ?? 0,
+          caps.maxRetrievalChars,
+        );
         return {
-          content: [{ type: "text", text: `## Query: "${result.query}"\n\n${result.answer}${sources}` }],
+          content: [{ type: "text", text: page.text + continuationNotice(page) }],
           details: { responseId: params.responseId },
         };
       }
@@ -216,8 +226,13 @@ export default function (pi: ExtensionAPI) {
           };
         }
         const title = result.title ? `**${result.title}**\n\n` : "";
+        const page = paginateContent(
+          `## ${result.url}\n\n${title}${result.content}`,
+          params.offset ?? 0,
+          caps.maxRetrievalChars,
+        );
         return {
-          content: [{ type: "text", text: `## ${result.url}\n\n${title}${result.content}` }],
+          content: [{ type: "text", text: page.text + continuationNotice(page) }],
           details: { responseId: params.responseId },
         };
       }

package/extensions/opl-webaccess/storage.ts

@@ -4,8 +4,6 @@ import type { StoredData } from "./types.js";
 const CUSTOM_TYPE = "web-access-results";
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 
-export const MAX_CONTENT_CHARS = 30_000;
-
 const store = new Map<string, StoredData>();
 
 /** Evict expired entries to prevent unbounded growth. */

package/extensions/opl-webaccess/utils.ts

@@ -15,6 +15,33 @@ export function truncate(text: string, maxChars: number): string {
   );
 }
 
+export interface ContentPage {
+  text: string;
+  offset: number;
+  totalChars: number;
+  nextOffset: number | null;
+}
+
+/** Slice stored content to one bounded page. Offsets past the end yield empty text. */
+export function paginateContent(text: string, offset: number, maxChars: number): ContentPage {
+  const totalChars = text.length;
+  const safeOffset = Number.isFinite(offset) ? Math.floor(offset) : 0;
+  const start = Math.min(Math.max(0, safeOffset), totalChars);
+  const end = Math.min(start + maxChars, totalChars);
+  return {
+    text: text.slice(start, end),
+    offset: start,
+    totalChars,
+    nextOffset: end < totalChars ? end : null,
+  };
+}
+
+/** Model-facing continuation metadata, empty when the page was complete. */
+export function continuationNotice(page: ContentPage): string {
+  if (page.nextOffset === null) return "";
+  return `\n\n[Content truncated at ${page.offset + page.text.length} of ${page.totalChars} chars. Continue with get_search_content offset=${page.nextOffset}.]`;
+}
+
 export function isPdfUrl(url: string): boolean {
   try {
     return new URL(url).pathname.toLowerCase().endsWith(".pdf");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlines/opl-pi-sht",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "opl-pi-sht (shouldHaveThat) Pi coding-agent extension kit: token-efficient context, safe modes, fingerprinted /init, model benchmarking, web access, and browser automation.",
   "repository": {
     "type": "git",
@@ -55,6 +55,6 @@
     "test:pi-host": "bun test tests/pi-host-loader.test.mjs"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.87.0"
+    "@earendil-works/pi-coding-agent": "^0.87.0"
   }
 }