@nklisch/pi-enhanced 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.3.1
+
+### Fixed
+
+- Rebundle `@nklisch/pi-plugins` 0.8.1 and `@nklisch/pi-subagents` 18.2.0-nklisch.1 with complete long-transcript search, match-centered excerpts, and stateless result paging.
+
 ## v0.3.0
 
 ### Changed

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [18.2.0-nklisch.1] - 2026-09-01
+
+### Fixed
+
+- Search complete transcript message, tool-argument, tool-name, call-id, and result fields instead of applying the returned-preview cap before matching.
+- Return bounded context around the actual matching passage with explicit full-search and source-range metadata.
+- Add stateless offset pagination with truthful next/previous offsets, distinct out-of-range outcomes, and guaranteed forward progress when byte or line bounds shorten a page.
+
 ## [18.2.0-nklisch.0] - 2026-09-01
 
 ### Added

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/README.md

@@ -236,8 +236,9 @@ Search a child transcript without steering or changing the child. The tool reads
 | `kind` | `all`, `messages`, `tool_calls`, or `tool_results` | no | Search scope; defaults to `all` |
 | `order` | `newest` or `oldest` | no | Result order; defaults to `newest` |
 | `limit` | integer 1–50 | no | Maximum entries; defaults to 20 |
+| `offset` | non-negative safe integer | no | Offset into the ordered matching entries; defaults to 0 |
 
-Arguments and results are capped before matching and output is bounded. Results identify the source and retained transcript path when one exists; use `/subagents:sessions` for the complete native transcript and `get_subagent_result` for status or final output.
+Matching is complete and case-insensitive literal across visible message text, tool names and IDs, arguments, and correlated results. Returned excerpts are bounded and center the first match with omission markers and source-range metadata; an omitted or empty query keeps beginning-of-entry previews. Tool names and call IDs are searched in full but exposed as bounded display previews, while stable entry IDs remain intact for overlay correlation. Output is also byte- and line-bounded, and every non-empty matching page emits at least one bounded entry. Details report the total, returned, before, and after counts plus copyable next/previous offsets when applicable. Use the next offset only from the returned details; it advances by entries actually emitted when output bounds shorten a page and is always greater than the requested offset. A zero-match query reports `no_matches`, while an offset beyond a non-empty result set reports `page_out_of_range`. Results identify the source and retained transcript path when one exists; use `/subagents:sessions` for the complete native transcript and `get_subagent_result` for status or final output.
 
 ### `steer_subagent`
 

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/architecture.md

@@ -365,11 +365,18 @@ src/
 ### Transcript query boundary
 
 `query_subagent_session` is a parent-only, read-only pull surface. Its pure
-`session/query.ts` projection correlates tool results to calls, caps searchable
-fields and excerpts, and applies literal case-insensitive matching, scope,
-ordering, and a 1–50 result limit on every call. It reads a live child session
-when retained and otherwise uses the same Pi JSONL/context adapter as native
-session navigation. No index or query state is persisted.
+`session/query.ts` projection correlates tool results to calls, searches every
+complete visible field with literal case-insensitive matching, and returns
+match-centered bounded excerpts with source-range metadata. Tool names and call
+IDs remain complete only in the projection-local search/correlation data;
+returned display values are bounded while stable entry IDs remain intact for the
+overlay. Scope, ordering, 1–50 result limits, and stateless numeric offsets page
+the ordered matching set; byte and line output bounds may shorten a page without
+advancing beyond entries actually returned, but a non-empty page always emits a
+bounded first entry. It reads a live child session when retained and otherwise
+uses the same Pi JSONL/context adapter as native session navigation. No index,
+cursor, or query state is persisted, and successful reads report complete
+search rather than a partial-search state.
 
 `/subagents:sessions` keeps Pi's native message, markdown, and tool-execution
 components for the transcript body. Its overlay owns only ephemeral search

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-subagents",
-  "version": "18.2.0-nklisch.0",
+  "version": "18.2.0-nklisch.1",
   "type": "module",
   "exports": {
     ".": {

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/session/query.ts

@@ -13,24 +13,33 @@ export type SessionQueryOrder = "newest" | "oldest";
 /** Overlay family filter; tool query parameters continue to use `kind`. */
 export type SessionQueryEntryFamily = "all" | "tools";
 export type ToolCallState = "pending" | "completed" | "failed";
+export type SessionQueryField = "text" | "toolName" | "toolCallId" | "arguments" | "result";
+export type SessionQueryOutcome = "matches" | "no_matches" | "page_out_of_range";
 
 export const DEFAULT_QUERY_LIMIT = 20;
 export const MIN_QUERY_LIMIT = 1;
 export const MAX_QUERY_LIMIT = 50;
 
-/** Caps are character caps: transcript content is text, not a byte protocol. */
-export const QUERY_SEARCH_FIELD_CAP = 8_192;
+/** Returned message text is bounded; matching always uses its complete source field. */
 export const MESSAGE_EXCERPT_CAP = 2_000;
 export const TOOL_ARGUMENTS_EXCERPT_CAP = 2_000;
 export const TOOL_RESULT_EXCERPT_CAP = 4_000;
 
 export interface QueryTruncation {
-  /** Search fields capped before matching, by field name. */
-  readonly searchFields: readonly string[];
   /** Returned excerpts capped for the caller, by field name. */
   readonly excerpts: readonly string[];
 }
 
+export interface QueryMatch {
+  /** The complete source field containing the first match. */
+  readonly field: SessionQueryField;
+  /** UTF-16 offsets in the complete, unmarked source field. */
+  readonly sourceRange: {
+    readonly start: number;
+    readonly end: number;
+  };
+}
+
 interface QueryEntryBase {
   /** Stable only within this projection; it is never written to a session. */
   readonly id: string;
@@ -38,21 +47,24 @@ interface QueryEntryBase {
   readonly sourceIndex: number;
   readonly timestamp?: number;
   readonly truncation: QueryTruncation;
+  /** Present only for a non-empty query; absent for prefix browsing. */
+  readonly match?: QueryMatch;
 }
 
 export interface MessageQueryEntry extends QueryEntryBase {
   readonly kind: "message";
   readonly role: "user" | "assistant";
-  /** Bounded visible message text. */
+  /** A prefix preview for browsing, or a match-centered excerpt for a query. */
   readonly text: string;
 }
 
 export interface ToolCallQueryEntry extends QueryEntryBase {
   readonly kind: "tool_call";
-  /** Undefined for a native bash-execution message, which has no call id. */
+  /** Bounded display preview; undefined for native bash-execution messages. */
   readonly toolCallId?: string;
+  /** Bounded display preview; the complete name remains query-local. */
   readonly toolName: string;
-  /** Bounded JSON arguments (or the command for a bash execution). */
+  /** A bounded JSON arguments preview, or a match-centered excerpt for a query. */
   readonly arguments: string;
   readonly state: ToolCallState;
   /** Bounded result text; undefined means pending/no correlated result, while `""` is a completed empty result. */
@@ -68,20 +80,36 @@ export interface SessionQueryOptions {
   readonly limit?: number;
   /** Restrict the result to the overlay's tool family without changing search fields. */
   readonly entryFamily?: SessionQueryEntryFamily;
+  /** Ordered matching-entry offset; no cursor or query state is retained. */
+  readonly offset?: number;
 }
 
 export interface SessionQueryResult {
   readonly entries: readonly SessionQueryEntry[];
-  /** Number of entries matching before the result limit is applied. */
+  /** Number of matching entries before paging. */
   readonly totalMatches: number;
-  readonly omittedCount: number;
+  /** Offset applied to the ordered matching-entry set. */
+  readonly offset: number;
+  /** Number of entries returned by this model page. */
+  readonly returnedCount: number;
+  /** Offset for the next page, when entries remain after this page. */
+  readonly nextOffset?: number;
+  /** Offset for a preceding page, when this result has a preceding page. */
+  readonly previousOffset?: number;
+  /** Matching entries before the returned page. */
+  readonly omittedBefore: number;
+  /** Matching entries after the returned page. */
+  readonly omittedAfter: number;
   readonly hasMore: boolean;
+  /** True whenever the transcript source was read successfully. */
+  readonly searchComplete: true;
+  readonly outcome: SessionQueryOutcome;
 }
 
 interface SearchableEntry {
   entry: SessionQueryEntry;
-  searchable: Readonly<Record<string, string>>;
-  rawSearchable: Readonly<Record<string, string>>;
+  /** Complete raw searchable fields; this object never escapes the query call. */
+  searchable: Readonly<Partial<Record<SessionQueryField, string>>>;
 }
 
 interface BoundedText {
@@ -104,8 +132,7 @@ function projectSearchableMessages(messages: readonly SessionMessage[]): Searcha
       const text = visibleText(message.content);
       if (text.trim()) {
         const bounded = bound(text, MESSAGE_EXCERPT_CAP);
-        const rawSearchable = { text };
-        const searchable = searchFields(rawSearchable);
+        const searchable = { text };
         projected.push({
           entry: {
             kind: "message",
@@ -114,10 +141,9 @@ function projectSearchableMessages(messages: readonly SessionMessage[]): Searcha
             ...(timestampOf(message) === undefined ? {} : { timestamp: timestampOf(message) }),
             role: message.role,
             text: bounded.value,
-            truncation: truncationFor(rawSearchable, { text: bounded }),
+            truncation: truncationFor({ text: bounded }),
           },
           searchable,
-          rawSearchable,
         });
       }
       if (message.role === "assistant") {
@@ -125,23 +151,30 @@ function projectSearchableMessages(messages: readonly SessionMessage[]): Searcha
           if (content.type !== "toolCall") continue;
           const callId = content.id;
           const args = stringifyArguments(content.arguments);
+          const boundedToolName = boundPreview(content.name, TOOL_ARGUMENTS_EXCERPT_CAP);
+          const boundedToolCallId = boundPreview(callId, TOOL_ARGUMENTS_EXCERPT_CAP);
           const boundedArgs = bound(args, TOOL_ARGUMENTS_EXCERPT_CAP);
-          const rawSearchable = { toolName: content.name, toolCallId: callId, arguments: args };
-          const searchable = searchFields(rawSearchable);
+          // Keep the complete name and id only in this projection-local search
+          // record. The public entry carries bounded display values, while its
+          // stable `id` remains the full correlation key used by the overlay.
+          const searchable = { toolName: content.name, toolCallId: callId, arguments: args };
           const call: SearchableEntry = {
             entry: {
               kind: "tool_call",
               id: callId,
               sourceIndex,
               ...(timestampOf(message) === undefined ? {} : { timestamp: timestampOf(message) }),
-              toolCallId: callId,
-              toolName: content.name,
+              toolCallId: boundedToolCallId.value,
+              toolName: boundedToolName.value,
               arguments: boundedArgs.value,
               state: "pending",
-              truncation: truncationFor(rawSearchable, { arguments: boundedArgs }),
+              truncation: truncationFor({
+                toolName: boundedToolName,
+                toolCallId: boundedToolCallId,
+                arguments: boundedArgs,
+              }),
             },
             searchable,
-            rawSearchable,
           };
           projected.push(call);
           calls.set(callId, call);
@@ -163,8 +196,7 @@ function projectSearchableMessages(messages: readonly SessionMessage[]): Searcha
       const result = state === "pending" ? undefined : message.output ?? "";
       const boundedArgs = bound(args, TOOL_ARGUMENTS_EXCERPT_CAP);
       const boundedResult = result === undefined ? undefined : bound(result, TOOL_RESULT_EXCERPT_CAP);
-      const rawSearchable = { toolName: "bash", arguments: args, ...(result === undefined ? {} : { result }) };
-      const searchable = searchFields(rawSearchable);
+      const searchable = { toolName: "bash", arguments: args, ...(result === undefined ? {} : { result }) };
       projected.push({
         entry: {
           kind: "tool_call",
@@ -175,13 +207,12 @@ function projectSearchableMessages(messages: readonly SessionMessage[]): Searcha
           arguments: boundedArgs.value,
           state,
           ...(boundedResult === undefined ? {} : { result: boundedResult.value }),
-          truncation: truncationFor(rawSearchable, {
+          truncation: truncationFor({
             arguments: boundedArgs,
             ...(boundedResult === undefined ? {} : { result: boundedResult }),
           }),
         },
         searchable,
-        rawSearchable,
       });
     }
   }
@@ -195,22 +226,20 @@ function projectSearchableMessages(messages: readonly SessionMessage[]): Searcha
     const current = call.entry as ToolCallQueryEntry;
     const resultText = visibleText(message.content);
     const boundedResult = bound(resultText, TOOL_RESULT_EXCERPT_CAP);
-    const rawSearchable = { ...call.rawSearchable, result: resultText };
-    const searchable = searchFields(rawSearchable);
+    const searchable = { ...call.searchable, result: resultText };
     const updated: ToolCallQueryEntry = {
       ...current,
       state: message.isError ? "failed" : "completed",
       // Preserve an empty but completed result as `""`; undefined means that
       // no correlated result has arrived yet.
       result: boundedResult.value,
-      truncation: truncationFor(rawSearchable, {
-        arguments: bound(call.rawSearchable.arguments ?? current.arguments, TOOL_ARGUMENTS_EXCERPT_CAP),
+      truncation: truncationFor({
+        arguments: bound(call.searchable.arguments ?? current.arguments, TOOL_ARGUMENTS_EXCERPT_CAP),
         result: boundedResult,
       }),
     };
     call.entry = updated;
     call.searchable = searchable;
-    call.rawSearchable = rawSearchable;
   }
 
   return projected;
@@ -222,23 +251,50 @@ export function querySession(
   options: SessionQueryOptions = {},
 ): SessionQueryResult {
   const limit = normalizeLimit(options.limit);
+  const offset = normalizeOffset(options.offset);
   const kind = options.kind ?? "all";
   const order = options.order ?? "newest";
   const query = options.query ?? "";
   const needle = query.toLowerCase();
   const projected = projectSearchableMessages(messages);
-  const matches = projected
-    .filter(({ entry }) => options.entryFamily !== "tools" || entry.kind === "tool_call")
-    .filter(({ entry }) => matchesKind(entry, kind))
-    .filter(({ searchable }) => matchesQuery(searchable, needle, kind))
-    .map(({ entry }) => entry);
-  const ordered = order === "newest" ? [...matches].reverse() : matches;
-  const entries = ordered.slice(0, limit);
+  const matching = projected.flatMap((candidate): SessionQueryEntry[] => {
+    if (options.entryFamily === "tools" && candidate.entry.kind !== "tool_call") return [];
+    if (!matchesKind(candidate.entry, kind)) return [];
+    if (needle.length === 0) return [candidate.entry];
+    const match = findFirstMatch(candidate.entry, candidate.searchable, needle, kind);
+    return match === undefined ? [] : [entryWithMatch(candidate, match)];
+  });
+  const ordered = order === "newest" ? [...matching].reverse() : matching;
+  const totalMatches = ordered.length;
+  const outcome: SessionQueryOutcome = totalMatches === 0
+    ? "no_matches"
+    : offset >= totalMatches
+      ? "page_out_of_range"
+      : "matches";
+  const entries = outcome === "matches"
+    ? ordered.slice(offset, Math.min(totalMatches, offset + limit))
+    : [];
+  const returnedCount = entries.length;
+  const nextOffset = offset < totalMatches && offset + returnedCount < totalMatches
+    ? offset + returnedCount
+    : undefined;
+  const previousOffset = totalMatches > 0 && offset > 0
+    ? Math.max(0, Math.min(Math.max(0, totalMatches - limit), offset - limit))
+    : undefined;
+  const omittedBefore = Math.min(offset, totalMatches);
+  const omittedAfter = Math.max(0, totalMatches - offset - returnedCount);
   return {
     entries,
-    totalMatches: matches.length,
-    omittedCount: Math.max(0, matches.length - entries.length),
-    hasMore: matches.length > entries.length,
+    totalMatches,
+    offset,
+    returnedCount,
+    ...(nextOffset === undefined ? {} : { nextOffset }),
+    ...(previousOffset === undefined ? {} : { previousOffset }),
+    omittedBefore,
+    omittedAfter,
+    hasMore: nextOffset !== undefined,
+    searchComplete: true,
+    outcome,
   };
 }
 
@@ -250,6 +306,14 @@ export function normalizeLimit(limit: number | undefined): number {
   return value;
 }
 
+export function normalizeOffset(offset: number | undefined): number {
+  const value = offset ?? 0;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new RangeError("offset must be a non-negative safe integer");
+  }
+  return value;
+}
+
 function matchesKind(entry: SessionQueryEntry, kind: SessionQueryKind): boolean {
   if (kind === "all") return true;
   if (kind === "messages") return entry.kind === "message";
@@ -257,20 +321,74 @@ function matchesKind(entry: SessionQueryEntry, kind: SessionQueryKind): boolean
   return entry.kind === "tool_call" && entry.result !== undefined;
 }
 
-function matchesQuery(
-  searchable: Readonly<Record<string, string>>,
+function findFirstMatch(
+  entry: SessionQueryEntry,
+  searchable: Readonly<Partial<Record<SessionQueryField, string>>>,
   needle: string,
   kind: SessionQueryKind,
-): boolean {
-  if (!needle) return true;
-  if (kind === "messages") return searchable.text?.toLowerCase().includes(needle) ?? false;
-  if (kind === "tool_calls") {
-    return [searchable.toolName, searchable.toolCallId, searchable.arguments]
-      .filter((value): value is string => value !== undefined)
-      .some((value) => value.toLowerCase().includes(needle));
+): QueryMatch | undefined {
+  const fields = entry.kind === "message"
+    ? ["text"] as const
+    : kind === "tool_results"
+      ? ["result"] as const
+      : kind === "tool_calls"
+        ? ["toolName", "toolCallId", "arguments"] as const
+        : ["toolName", "toolCallId", "arguments", "result"] as const;
+  for (const field of fields) {
+    const value = searchable[field];
+    if (value === undefined) continue;
+    const lowered = value.toLowerCase();
+    const matchStart = lowered.indexOf(needle);
+    if (matchStart < 0) continue;
+    const matchEnd = matchStart + needle.length;
+    const sourceStart = sourceOffsetForLower(value, matchStart, false);
+    const sourceEnd = Math.max(sourceStart + 1, sourceOffsetForLower(value, matchEnd, true));
+    return { field, sourceRange: { start: sourceStart, end: Math.min(value.length, sourceEnd) } };
+  }
+  return undefined;
+}
+
+function entryWithMatch(candidate: SearchableEntry, match: QueryMatch): SessionQueryEntry {
+  const { entry, searchable } = candidate;
+  if (entry.kind === "message") {
+    const text = searchable.text ?? entry.text;
+    const bounded = boundAroundMatch(text, match.sourceRange, MESSAGE_EXCERPT_CAP);
+    return { ...entry, text: bounded.value, truncation: truncationFor({ text: bounded }), match };
   }
-  if (kind === "tool_results") return searchable.result?.toLowerCase().includes(needle) ?? false;
-  return Object.values(searchable).some((value) => value.toLowerCase().includes(needle));
+
+  const toolName = searchable.toolName ?? entry.toolName;
+  const boundedToolName = match.field === "toolName"
+    ? boundAroundMatch(toolName, match.sourceRange, TOOL_ARGUMENTS_EXCERPT_CAP)
+    : boundPreview(toolName, TOOL_ARGUMENTS_EXCERPT_CAP);
+  const toolCallId = searchable.toolCallId;
+  const boundedToolCallId = toolCallId === undefined
+    ? undefined
+    : match.field === "toolCallId"
+      ? boundAroundMatch(toolCallId, match.sourceRange, TOOL_ARGUMENTS_EXCERPT_CAP)
+      : boundPreview(toolCallId, TOOL_ARGUMENTS_EXCERPT_CAP);
+  const argumentsText = searchable.arguments ?? entry.arguments;
+  const boundedArguments = match.field === "arguments"
+    ? boundAroundMatch(argumentsText, match.sourceRange, TOOL_ARGUMENTS_EXCERPT_CAP)
+    : bound(argumentsText, TOOL_ARGUMENTS_EXCERPT_CAP);
+  const boundedResult = searchable.result === undefined
+    ? undefined
+    : match.field === "result"
+      ? boundAroundMatch(searchable.result, match.sourceRange, TOOL_RESULT_EXCERPT_CAP)
+      : bound(searchable.result, TOOL_RESULT_EXCERPT_CAP);
+  return {
+    ...entry,
+    toolName: boundedToolName.value,
+    ...(boundedToolCallId === undefined ? {} : { toolCallId: boundedToolCallId.value }),
+    arguments: boundedArguments.value,
+    ...(boundedResult === undefined ? {} : { result: boundedResult.value }),
+    truncation: truncationFor({
+      toolName: boundedToolName,
+      ...(boundedToolCallId === undefined ? {} : { toolCallId: boundedToolCallId }),
+      arguments: boundedArguments,
+      ...(boundedResult === undefined ? {} : { result: boundedResult }),
+    }),
+    match,
+  };
 }
 
 function visibleText(content: unknown): string {
@@ -301,27 +419,70 @@ function messageIdentity(role: "user" | "assistant", sourceIndex: number, timest
   return `message:${role}:${sourceIndex}${typeof timestamp === "number" ? `:${timestamp}` : ""}`;
 }
 
-function capForSearch(value: string): string {
-  return value.length > QUERY_SEARCH_FIELD_CAP ? value.slice(0, QUERY_SEARCH_FIELD_CAP) : value;
+function bound(value: string, cap: number): BoundedText {
+  return value.length > cap ? { value: value.slice(0, cap), truncated: true } : { value, truncated: false };
 }
 
-function searchFields(fields: Readonly<Record<string, string>>): Readonly<Record<string, string>> {
-  return Object.fromEntries(Object.entries(fields).map(([name, value]) => [name, capForSearch(value)]));
+/** Prefix previews identify omitted metadata without exposing the full field. */
+function boundPreview(value: string, cap: number): BoundedText {
+  if (value.length <= cap) return { value, truncated: false };
+  const marker = "…";
+  const contentCap = Math.max(0, cap - marker.length);
+  return { value: `${value.slice(0, contentCap)}${marker}`, truncated: true };
 }
 
-function bound(value: string, cap: number): BoundedText {
-  return value.length > cap ? { value: value.slice(0, cap), truncated: true } : { value, truncated: false };
+/**
+ * Keep the first match visible while spending the excerpt budget on context.
+ * The source range remains in raw-field coordinates; markers are presentation
+ * text and are not included in that range.
+ */
+function boundAroundMatch(value: string, sourceRange: { start: number; end: number }, cap: number): BoundedText {
+  if (value.length <= cap) return { value, truncated: false };
+  const contentCap = Math.max(1, cap - 2);
+  const matchStart = Math.max(0, Math.min(value.length, sourceRange.start));
+  const matchEnd = Math.max(matchStart + 1, Math.min(value.length, sourceRange.end));
+  if (matchEnd - matchStart >= contentCap) {
+    const end = Math.min(value.length, matchStart + contentCap);
+    return { value: `${value.slice(0, matchStart) ? "…" : ""}${value.slice(matchStart, end)}${end < value.length ? "…" : ""}`, truncated: true };
+  }
+
+  const windowStart = Math.max(0, matchEnd - contentCap);
+  const windowEnd = Math.min(matchStart, value.length - contentCap);
+  const centeredStart = matchStart - Math.floor((contentCap - (matchEnd - matchStart)) / 2);
+  const start = Math.max(windowStart, Math.min(windowEnd, centeredStart));
+  const end = Math.min(value.length, start + contentCap);
+  return {
+    value: `${start > 0 ? "…" : ""}${value.slice(start, end)}${end < value.length ? "…" : ""}`,
+    truncated: true,
+  };
 }
 
-function truncationFor(
-  rawSearchable: Readonly<Record<string, string>>,
-  excerpts: Readonly<Record<string, BoundedText>>,
-): QueryTruncation {
-  const searchFields = Object.entries(rawSearchable)
-    .filter(([, value]) => value.length > QUERY_SEARCH_FIELD_CAP)
-    .map(([name]) => name);
-  const excerptFields = Object.entries(excerpts)
-    .filter(([, value]) => value.truncated)
-    .map(([name]) => name);
-  return { searchFields, excerpts: excerptFields };
+/**
+ * Map an offset in the lower-cased field back to the original UTF-16 field.
+ * Matching itself uses `value.toLowerCase()` as a whole; this linear walk only
+ * accounts for each code point's lower-case UTF-16 width, including expanding
+ * mappings such as `İ` → `i` plus a combining dot.
+ */
+function sourceOffsetForLower(value: string, lowerOffset: number, end: boolean): number {
+  let sourceOffset = 0;
+  let lowerPosition = 0;
+  for (const character of value) {
+    if (lowerOffset <= lowerPosition) return sourceOffset;
+    const lowerLength = character.toLowerCase().length;
+    const nextLowerPosition = lowerPosition + lowerLength;
+    if (lowerOffset < nextLowerPosition || (end && lowerOffset === nextLowerPosition)) {
+      return end ? sourceOffset + character.length : sourceOffset;
+    }
+    sourceOffset += character.length;
+    lowerPosition = nextLowerPosition;
+  }
+  return sourceOffset;
+}
+
+function truncationFor(excerpts: Readonly<Record<string, BoundedText>>): QueryTruncation {
+  return {
+    excerpts: Object.entries(excerpts)
+      .filter(([, value]) => value.truncated)
+      .map(([name]) => name),
+  };
 }

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/src/tools/query-session-tool.ts

@@ -19,7 +19,7 @@ const MAX_QUERY_OUTPUT_LINES = 2_000;
 // Leave room for the summary, source path, omission tail, and a final line/
 // byte boundary. The entry budget is intentionally smaller than Pi's limits;
 // entries are additionally checked against the actual fixed text below.
-const MAX_QUERY_ENTRY_BYTES = 40 * 1024;
+const MAX_QUERY_ENTRY_BYTES = 39 * 1024;
 const MAX_QUERY_ENTRY_LINES = 1_800;
 const MAX_QUERY_METADATA_LINE_BYTES = 2_048;
 const MAX_QUERY_TRANSCRIPT_PATH_BYTES = 1_024;
@@ -27,7 +27,7 @@ const utf8Encoder = new TextEncoder();
 const VALID_KINDS = new Set<SessionQueryKind>(["all", "messages", "tool_calls", "tool_results"]);
 const VALID_ORDERS = new Set<SessionQueryOrder>(["newest", "oldest"]);
 
-export type QuerySessionOutcome = "matches" | "no_matches" | "transcript_unavailable" | "not_found" | "read_error";
+export type QuerySessionOutcome = "matches" | "no_matches" | "page_out_of_range" | "transcript_unavailable" | "not_found" | "read_error";
 
 export interface QuerySessionDetails {
   readonly outcome: QuerySessionOutcome;
@@ -46,10 +46,17 @@ export interface QuerySessionDetails {
   readonly kind?: SessionQueryKind;
   readonly order?: SessionQueryOrder;
   readonly limit?: number;
+  readonly offset?: number;
   readonly entries?: readonly SessionQueryEntry[];
   readonly totalMatches?: number;
+  readonly returnedCount?: number;
+  readonly nextOffset?: number;
+  readonly previousOffset?: number;
+  readonly omittedBefore?: number;
+  readonly omittedAfter?: number;
   readonly hasMore?: boolean;
-  readonly omittedCount?: number;
+  /** True means every searchable field was examined, not just a preview prefix. */
+  readonly searchComplete?: boolean;
   readonly truncation?: {
     readonly output: boolean;
     readonly omittedMatches: number;
@@ -79,6 +86,7 @@ export class QuerySessionTool {
       kind?: SessionQueryKind;
       order?: SessionQueryOrder;
       limit?: number;
+      offset?: number;
     },
     _signal: AbortSignal | undefined,
     _onUpdate: unknown,
@@ -131,18 +139,26 @@ export class QuerySessionTool {
       kind: params.kind,
       order: params.order,
       limit: params.limit,
+      offset: params.offset,
     });
     const summary = boundedOutputLine(summaryLine(base), MAX_QUERY_METADATA_LINE_BYTES);
     const sourceDescription = boundedOutputLine(
       `${source}${record.outputFile ? ` (${record.outputFile})` : ""}`,
       MAX_QUERY_METADATA_LINE_BYTES,
     );
-    const prefix = `${summary}\nSource: ${sourceDescription}\n`;
-    // Reserve the largest possible omission tail before selecting entries. This
-    // prevents a later bounds notice from pushing an otherwise-fitting body
-    // over Pi's byte or line ceiling.
-    const maximumOmittedCount = result.omittedCount + result.entries.length;
-    const reservedTail = omissionTail(maximumOmittedCount, record.outputFile);
+    const prefix = `${summary}\nSource: ${sourceDescription}\nSearch: complete (full transcript fields).\n`;
+    // Reserve the largest possible omission/navigation tail before selecting
+    // entries. This keeps a later bounds notice from pushing the body over
+    // Pi's byte or line ceiling.
+    const maximumOmittedCount = result.omittedBefore + result.omittedAfter + result.entries.length;
+    const reservedTail = omissionTail(
+      maximumOmittedCount,
+      maximumOmittedCount,
+      maximumOmittedCount,
+      result.nextOffset,
+      result.previousOffset,
+      record.outputFile,
+    );
     const output = formatEntries(
       result.entries,
       Math.min(
@@ -154,8 +170,16 @@ export class QuerySessionTool {
         Math.max(0, MAX_QUERY_OUTPUT_LINES - lineCount(prefix) - lineCount(reservedTail) - 1),
       ),
     );
-    const omittedCount = result.omittedCount + output.omittedCount;
-    const outcome: QuerySessionOutcome = result.entries.length > 0 ? "matches" : "no_matches";
+    const returnedCount = output.entries.length;
+    const omittedBefore = result.omittedBefore;
+    const omittedAfter = Math.max(0, result.totalMatches - result.offset - returnedCount);
+    // Recompute this from entries that really made it into the output. If the
+    // byte/line budget drops entries from a page, the next request starts after
+    // only those entries and cannot skip an unseen match.
+    const nextOffset = result.outcome === "matches" && returnedCount > 0 && result.offset + returnedCount < result.totalMatches
+      ? result.offset + returnedCount
+      : undefined;
+    const outcome = result.outcome;
     const details: QuerySessionDetails = {
       ...base,
       outcome,
@@ -165,22 +189,37 @@ export class QuerySessionTool {
       kind: params.kind ?? "all",
       order: params.order ?? "newest",
       limit: params.limit ?? DEFAULT_QUERY_LIMIT,
+      offset: result.offset,
       entries: output.entries,
       totalMatches: result.totalMatches,
-      hasMore: omittedCount > 0,
-      omittedCount,
-      ...(omittedCount > 0 ? {
+      returnedCount,
+      ...(nextOffset === undefined ? {} : { nextOffset }),
+      ...(result.previousOffset === undefined ? {} : { previousOffset: result.previousOffset }),
+      omittedBefore,
+      omittedAfter,
+      hasMore: nextOffset !== undefined,
+      searchComplete: true,
+      ...(output.omittedCount > 0 ? {
         truncation: {
-          output: output.omittedCount > 0,
-          omittedMatches: omittedCount,
+          output: true,
+          omittedMatches: output.omittedCount,
           ...(record.outputFile ? { transcriptPath: record.outputFile } : {}),
         },
       } : {}),
     };
-    const body = result.entries.length === 0
+    const body = outcome === "no_matches"
       ? "No transcript entries match the requested query."
-      : output.lines.join("\n");
-    const tail = omissionTail(omittedCount, record.outputFile);
+      : outcome === "page_out_of_range"
+        ? `No transcript page starts at offset ${result.offset}; ${result.totalMatches} matching entr${result.totalMatches === 1 ? "y is" : "ies are"} available.`
+        : output.lines.join("\n");
+    const tail = omissionTail(
+      omittedBefore,
+      omittedAfter,
+      output.omittedCount,
+      nextOffset,
+      result.previousOffset,
+      record.outputFile,
+    );
     return textResult(`${prefix}${body}${tail}`, details);
   }
 
@@ -189,10 +228,10 @@ export class QuerySessionTool {
       name: "query_subagent_session" as const,
       label: "Query Subagent Session",
       promptSnippet: "query_subagent_session: Search a bounded child transcript without steering it.",
-      description: "Query a subagent's recent or matching messages and tool calls. Search is case-insensitive literal text, bounded, and read-only; use get_subagent_result for the final result and list_subagents for fleet triage.",
+      description: "Query a subagent's recent or matching messages and tool calls. Search is complete, case-insensitive literal text over full fields, bounded only in returned excerpts/output, and read-only; use get_subagent_result for the final result and list_subagents for fleet triage.",
       parameters: Type.Object({
         agent_id: Type.String({ description: "The subagent ID to inspect." }),
-        query: Type.Optional(Type.String({ description: "Case-insensitive literal text. Omit or use an empty string for recent entries." })),
+        query: Type.Optional(Type.String({ description: "Case-insensitive literal text. Omit or use an empty string for beginning-of-entry previews." })),
         kind: Type.Optional(Type.Union([
           Type.Literal("all"),
           Type.Literal("messages"),
@@ -204,6 +243,7 @@ export class QuerySessionTool {
           Type.Literal("oldest"),
         ], { description: "Result order. Defaults to newest." })),
         limit: Type.Optional(Type.Integer({ minimum: MIN_QUERY_LIMIT, maximum: MAX_QUERY_LIMIT, description: "Maximum entries, 1-50; defaults to 20." })),
+        offset: Type.Optional(Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER, description: "Non-negative safe integer offset into the ordered matching entries; defaults to 0." })),
       }),
       execute: (toolCallId: string, params: {
         agent_id?: string;
@@ -211,6 +251,7 @@ export class QuerySessionTool {
         kind?: SessionQueryKind;
         order?: SessionQueryOrder;
         limit?: number;
+        offset?: number;
       }, signal: AbortSignal | undefined, onUpdate: unknown, ctx: unknown) => this.execute(toolCallId, params, signal, onUpdate, ctx),
     });
   }
@@ -222,6 +263,7 @@ function validateParams(params: {
   kind?: SessionQueryKind;
   order?: SessionQueryOrder;
   limit?: number;
+  offset?: number;
 }): string | undefined {
   if (typeof params.agent_id !== "string" || params.agent_id.length === 0) return "agent_id must be a non-empty string";
   if (params.query !== undefined && typeof params.query !== "string") return "query must be a string";
@@ -230,6 +272,8 @@ function validateParams(params: {
   if (params.limit !== undefined && (!Number.isInteger(params.limit) || params.limit < MIN_QUERY_LIMIT || params.limit > MAX_QUERY_LIMIT)) {
     return `limit must be an integer from ${MIN_QUERY_LIMIT} to ${MAX_QUERY_LIMIT}`;
   }
+  if (params.offset !== undefined && !Number.isSafeInteger(params.offset)) return "offset must be a non-negative safe integer";
+  if (params.offset !== undefined && params.offset < 0) return "offset must be a non-negative safe integer";
   return undefined;
 }
 
@@ -277,7 +321,25 @@ function formatEntries(
     const addition = selected.length === 0 ? line : `\n${line}`;
     const additionBytes = utf8ByteLength(addition);
     const additionLines = lineCount(addition);
-    if (bytes + additionBytes > maxBytes || lineTotal + additionLines > maxLines) break;
+    if (bytes + additionBytes > maxBytes || lineTotal + additionLines > maxLines) {
+      // A newline-dense first entry can exceed the line budget even though its
+      // projection is character-bounded. Compact only this fallback
+      // representation so a real match can always make progress; later pages
+      // still use the normal output bounds and the returned count remains exact.
+      if (selected.length === 0) {
+        const compactLine = formatEntry(entry, true);
+        const compactAddition = compactLine;
+        const compactBytes = utf8ByteLength(compactAddition);
+        const compactLines = lineCount(compactAddition);
+        if (compactBytes <= maxBytes && compactLines <= maxLines) {
+          selected.push(entry);
+          lines.push(compactLine);
+          bytes = compactBytes;
+          lineTotal = compactLines;
+        }
+      }
+      break;
+    }
     selected.push(entry);
     lines.push(line);
     bytes += additionBytes;
@@ -286,13 +348,21 @@ function formatEntries(
   return { entries: selected, lines, omittedCount: entries.length - selected.length };
 }
 
-function formatEntry(entry: SessionQueryEntry): string {
+function formatEntry(entry: SessionQueryEntry, compact = false): string {
+  const display = (value: string): string => compact ? compactLineBreaks(value) : value;
+  const match = entry.match === undefined
+    ? ""
+    : ` · match=${entry.match.field} [${entry.match.sourceRange.start},${entry.match.sourceRange.end})`;
   if (entry.kind === "message") {
-    return `[${entry.role}] ${entry.id}\n${entry.text}`;
+    return `[${entry.role}] ${entry.id}${match}\n${display(entry.text)}`;
   }
-  const callId = entry.toolCallId ? ` id=${entry.toolCallId}` : "";
-  const result = entry.result === undefined ? "" : `\nresult: ${entry.result}`;
-  return `[tool ${entry.toolName}${callId} · ${entry.state}] ${entry.id}\narguments: ${entry.arguments}${result}`;
+  const callIdentity = entry.toolCallId ?? entry.id;
+  const result = entry.result === undefined ? "" : `\nresult: ${display(entry.result)}`;
+  return `[tool ${display(entry.toolName)} · ${entry.state}] id=${display(callIdentity)}${match}\narguments: ${display(entry.arguments)}${result}`;
+}
+
+function compactLineBreaks(value: string): string {
+  return value.replace(/\r\n|\r|\n/g, " ");
 }
 
 function utf8ByteLength(value: string): number {
@@ -321,10 +391,22 @@ function boundedOutputLine(value: string, maxBytes: number): string {
   return `${output}${ellipsis}`;
 }
 
-function omissionTail(omittedCount: number, transcriptPath: string | undefined): string {
-  if (omittedCount <= 0) return "";
-  const path = transcriptPath
-    ? ` Full transcript: ${boundedOutputLine(transcriptPath, MAX_QUERY_TRANSCRIPT_PATH_BYTES)}`
-    : "";
-  return `\n\n${omittedCount} matching entr${omittedCount === 1 ? "y was" : "ies were"} omitted by the bounds.${path}`;
+function omissionTail(
+  omittedBefore: number,
+  omittedAfter: number,
+  outputOmitted: number,
+  nextOffset: number | undefined,
+  previousOffset: number | undefined,
+  transcriptPath: string | undefined,
+): string {
+  const lines: string[] = [];
+  if (omittedBefore > 0) lines.push(`${omittedBefore} matching entr${omittedBefore === 1 ? "y precedes" : "ies precede"} this page.`);
+  if (omittedAfter > 0) lines.push(`${omittedAfter} matching entr${omittedAfter === 1 ? "y remains" : "ies remain"} after this page.`);
+  if (outputOmitted > 0) lines.push(`${outputOmitted} entries from this page were omitted by the output bounds.`);
+  if (nextOffset !== undefined) lines.push(`More matches available; repeat with offset: ${nextOffset}.`);
+  if (previousOffset !== undefined) lines.push(`Previous page available; repeat with offset: ${previousOffset}.`);
+  if (transcriptPath && outputOmitted > 0) {
+    lines.push(`Full transcript: ${boundedOutputLine(transcriptPath, MAX_QUERY_TRANSCRIPT_PATH_BYTES)}`);
+  }
+  return lines.length === 0 ? "" : `\n\n${lines.join("\n")}`;
 }

package/node_modules/@nklisch/pi-plugins/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-plugins",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "private": false,
   "description": "A small filesystem-first marketplace and plugin host for Pi.",
   "license": "MIT",
@@ -63,7 +63,7 @@
   ],
   "dependencies": {
     "@nklisch/pi-mcp-adapter": "2.21.0-nklisch.2",
-    "@nklisch/pi-subagents": "18.2.0-nklisch.0",
+    "@nklisch/pi-subagents": "18.2.0-nklisch.1",
     "jiti": "2.7.0"
   },
   "devDependencies": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nklisch/pi-enhanced",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Pi, enhanced — one install for nklisch's full harness: policy-gated command review, plugin marketplace, subagents, background tasks, research tools, search, model modes, and a curated UX set.",
   "author": {
     "name": "nklisch"