@hassangameryt/freeflow 0.4.0 → 0.6.0

package/pi-extension/src/context-virtualization/types.ts

@@ -0,0 +1,92 @@
+import type { ContextSourceIdentity } from "../freeflow-context/types.js";
+
+export { CONTEXT_REF_PREFIX, contextRefForEntry, entryIdFromContextRef } from "../freeflow-context/types.js";
+export type {
+  ContextRequestSnapshot,
+  ContextSourceKind,
+  ContextSourceIdentity,
+  ProjectedContextSource,
+  ResolvedContextEntry,
+  ResolvedContextSource,
+  SourceProjectionOutcome,
+} from "../freeflow-context/types.js";
+
+export const CONTEXT_PROJECTION_ENTRY = "freeflow-context-projection";
+export const CONTEXT_PROJECTION_VERSION = 1 as const;
+
+export type ContextProjectionMode = "full" | "archived";
+export type ContextProjectionActor = "model" | "user";
+
+export type ContextProjection = { mode: "full" } | { mode: "archived"; retained?: string };
+
+export type ContextProjectionState = ContextProjection & {
+  source: ContextSourceIdentity;
+};
+
+export type ContextProjectionChange = {
+  source: ContextSourceIdentity;
+  projection: ContextProjection;
+};
+
+export type ContextProjectionJournal = {
+  version: typeof CONTEXT_PROJECTION_VERSION;
+  actor: ContextProjectionActor;
+  changes?: ContextProjectionChange[];
+  reset?: "all";
+};
+
+export type ContextProjectionResult = {
+  messages: any[];
+  changed: boolean;
+  available: boolean;
+  generation?: number;
+};
+
+export type ContextAvailability = "active" | "history-only" | "unresolved";
+
+export type ContextListItem = {
+  ref: string;
+  entryId: string;
+  toolCallId?: string;
+  toolName?: string;
+  mode: ContextProjectionMode;
+  retained?: string;
+  originalCharacters: number;
+  projectedCharacters: number;
+  availability: ContextAvailability;
+};
+
+export type ContextStatus = {
+  available: boolean;
+  unavailableReason?: string;
+  sessionId: string;
+  branchLeafId?: string | null;
+  counts: {
+    full: number;
+    archived: number;
+    retained: number;
+  };
+  originalCharacters: number;
+  projectedCharacters: number;
+  historyOnly: number;
+  unresolved: number;
+  items: ContextListItem[];
+};
+
+export type ContextOperationResult = {
+  status: "ok" | "rejected" | "unavailable";
+  operation: "archive" | "restore" | "reset";
+  changed: string[];
+  message?: string;
+  retained?: Record<string, string>;
+  availability?: Record<string, ContextAvailability>;
+};
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function projectionCharacters(projection: ContextProjection): number {
+  if (projection.mode === "full") return 0;
+  return projection.retained?.length ?? 0;
+}

package/pi-extension/src/conversation-history/passages.ts

@@ -0,0 +1,81 @@
+export const PASSAGE_TARGET_CHARACTERS = 2_000;
+export const PASSAGE_OVERLAP_CHARACTERS = 200;
+export const SNIPPET_MAX_CHARACTERS = 400;
+
+export type TextPassage = {
+  text: string;
+  start: number;
+  end: number;
+  tokens: string[];
+  length: number;
+};
+
+export function normalizeText(value: string): string {
+  return value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/g, " ").trim();
+}
+
+export function tokenize(value: string): string[] {
+  return normalizeText(value).match(/[\p{L}\p{N}_]+(?:[./:@#$%+-][\p{L}\p{N}_]+)*/gu) ?? [];
+}
+
+export function unique(values: readonly string[]): string[] {
+  return [...new Set(values)];
+}
+
+export function throwIfAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  const error = new Error("conversation_history_search_cancelled");
+  error.name = "AbortError";
+  throw error;
+}
+
+function passageEnd(text: string, start: number): number {
+  const target = Math.min(text.length, start + PASSAGE_TARGET_CHARACTERS);
+  if (target === text.length) return target;
+  const paragraphBreak = text.lastIndexOf("\n\n", target);
+  if (paragraphBreak > start + PASSAGE_TARGET_CHARACTERS / 2) return paragraphBreak + 2;
+  const lineBreak = text.lastIndexOf("\n", target);
+  if (lineBreak > start + PASSAGE_TARGET_CHARACTERS / 2) return lineBreak + 1;
+  return target;
+}
+
+export function splitTextIntoPassages(text: string, signal?: AbortSignal): TextPassage[] {
+  throwIfAborted(signal);
+  if (text.length <= PASSAGE_TARGET_CHARACTERS) {
+    return [{ text, start: 0, end: text.length, tokens: tokenize(text), length: Math.max(1, tokenize(text).length) }];
+  }
+  const result: TextPassage[] = [];
+  let start = 0;
+  while (start < text.length) {
+    throwIfAborted(signal);
+    const end = passageEnd(text, start);
+    const passageText = text.slice(start, end);
+    const tokens = tokenize(passageText);
+    result.push({ text: passageText, start, end, tokens, length: Math.max(1, tokens.length) });
+    if (end >= text.length) break;
+    start = Math.max(start + 1, end - PASSAGE_OVERLAP_CHARACTERS);
+  }
+  return result;
+}
+
+export function snippet(text: string, phrase: string, terms: readonly string[]): string {
+  if (text.length <= SNIPPET_MAX_CHARACTERS) return text;
+  const lower = text.toLocaleLowerCase();
+  const phraseIndex = phrase ? lower.indexOf(phrase) : -1;
+  const termIndex =
+    phraseIndex >= 0
+      ? phraseIndex
+      : terms.reduce((best, term) => {
+          const index = lower.indexOf(term);
+          return index >= 0 && (best < 0 || index < best) ? index : best;
+        }, -1);
+  const center = termIndex >= 0 ? termIndex : 0;
+  let start = Math.max(0, center - Math.floor(SNIPPET_MAX_CHARACTERS / 3));
+  const end = Math.min(text.length, start + SNIPPET_MAX_CHARACTERS);
+  if (end - start < SNIPPET_MAX_CHARACTERS) start = Math.max(0, end - SNIPPET_MAX_CHARACTERS);
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < text.length ? "…" : "";
+  const available = SNIPPET_MAX_CHARACTERS - prefix.length - suffix.length;
+  const body = text.slice(start, start + available);
+  return `${prefix}${body}${suffix}`;
+}

package/pi-extension/src/conversation-history/ranking.ts

@@ -0,0 +1,155 @@
+import type { ConversationSearchEntry } from "./types.js";
+import {
+  normalizeText,
+  splitTextIntoPassages,
+  throwIfAborted,
+  tokenize,
+  unique,
+  type TextPassage,
+} from "./passages.js";
+
+export const BM25_K1 = 1.2;
+export const BM25_B = 0.75;
+
+export type RankedPassage = {
+  entry: ConversationSearchEntry;
+  passage: TextPassage;
+  exactPhrase: boolean;
+  matchedTerms: string[];
+  score: number;
+};
+
+type RankedTextPassage = Omit<RankedPassage, "entry">;
+
+type PassageInput = {
+  entry?: ConversationSearchEntry;
+  passage: TextPassage;
+  exactPhrase: boolean;
+  matchedTerms: string[];
+};
+
+function bm25Score(
+  tokens: readonly string[],
+  terms: readonly string[],
+  documentFrequency: ReadonlyMap<string, number>,
+  documentCount: number,
+  averageLength: number,
+): number {
+  const counts = new Map<string, number>();
+  for (const token of tokens) counts.set(token, (counts.get(token) ?? 0) + 1);
+  const length = Math.max(1, tokens.length);
+  let score = 0;
+  for (const term of terms) {
+    const termFrequency = counts.get(term) ?? 0;
+    if (termFrequency === 0) continue;
+    const df = documentFrequency.get(term) ?? 0;
+    const inverseDocumentFrequency = Math.log(1 + (documentCount - df + 0.5) / (df + 0.5));
+    const normalization = BM25_K1 * (1 - BM25_B + BM25_B * (length / Math.max(1, averageLength)));
+    score += inverseDocumentFrequency * ((termFrequency * (BM25_K1 + 1)) / (termFrequency + normalization));
+  }
+  return score;
+}
+
+function comparePassages(left: RankedPassage, right: RankedPassage): number {
+  if (left.exactPhrase !== right.exactPhrase) return left.exactPhrase ? -1 : 1;
+  if (left.score !== right.score) return right.score - left.score;
+  if (left.matchedTerms.length !== right.matchedTerms.length) {
+    return right.matchedTerms.length - left.matchedTerms.length;
+  }
+  if (left.entry.position !== right.entry.position) return right.entry.position - left.entry.position;
+  return left.passage.start - right.passage.start;
+}
+
+function compareTextPassages(left: RankedTextPassage, right: RankedTextPassage): number {
+  if (left.exactPhrase !== right.exactPhrase) return left.exactPhrase ? -1 : 1;
+  if (left.score !== right.score) return right.score - left.score;
+  if (left.matchedTerms.length !== right.matchedTerms.length) {
+    return right.matchedTerms.length - left.matchedTerms.length;
+  }
+  return left.passage.start - right.passage.start;
+}
+
+function rankInputs<T extends PassageInput>(
+  inputs: T[],
+  terms: string[],
+  signal?: AbortSignal,
+): Array<T & { score: number }> {
+  const documentFrequency = new Map<string, number>();
+  for (const input of inputs) {
+    throwIfAborted(signal);
+    for (const term of unique(input.passage.tokens)) {
+      documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
+    }
+  }
+  const averageLength =
+    inputs.length === 0 ? 1 : inputs.reduce((total, input) => total + input.passage.length, 0) / inputs.length;
+  const matching: T[] = [];
+  for (const input of inputs) {
+    throwIfAborted(signal);
+    if (input.matchedTerms.length > 0 || input.exactPhrase) matching.push(input);
+  }
+  return matching
+    .map((input) => ({
+      ...input,
+      score: bm25Score(input.passage.tokens, terms, documentFrequency, inputs.length, averageLength),
+    }))
+    .sort((left, right) => {
+      if (left.entry && right.entry) {
+        return comparePassages(
+          { ...left, entry: left.entry } as RankedPassage,
+          { ...right, entry: right.entry } as RankedPassage,
+        );
+      }
+      return compareTextPassages(left as RankedTextPassage & T, right as RankedTextPassage & T);
+    });
+}
+
+export function rankMatchingPassages(
+  entries: readonly ConversationSearchEntry[],
+  query: string,
+  signal?: AbortSignal,
+): RankedPassage[] {
+  throwIfAborted(signal);
+  const normalizedQuery = normalizeText(query);
+  const terms = unique(tokenize(query));
+  if (!normalizedQuery || terms.length === 0) return [];
+  const inputs: PassageInput[] = [];
+  for (const entry of entries) {
+    throwIfAborted(signal);
+    for (const passage of splitTextIntoPassages(entry.text, signal)) {
+      const normalizedPassage = normalizeText(passage.text);
+      inputs.push({
+        entry,
+        passage,
+        exactPhrase: normalizedPassage.includes(normalizedQuery),
+        matchedTerms: terms.filter((term) => passage.tokens.includes(term)),
+      });
+    }
+  }
+  return rankInputs(inputs, terms, signal) as RankedPassage[];
+}
+
+export function strongestTextPassage(text: string, query: string): RankedTextPassage | undefined {
+  const normalizedQuery = normalizeText(query);
+  const terms = unique(tokenize(query));
+  if (!normalizedQuery || terms.length === 0) return undefined;
+  const inputs: PassageInput[] = splitTextIntoPassages(text).map((passage) => ({
+    passage,
+    exactPhrase: normalizeText(passage.text).includes(normalizedQuery),
+    matchedTerms: terms.filter((term) => passage.tokens.includes(term)),
+  }));
+  return rankInputs(inputs, terms)[0] as RankedTextPassage | undefined;
+}
+
+export function focusedWindow(text: string, focus: string, maxCharacters: number): string | undefined {
+  const strongest = strongestTextPassage(text, focus);
+  if (!strongest) return undefined;
+  const center = Math.floor((strongest.passage.start + strongest.passage.end) / 2);
+  const proposedStart = Math.max(0, Math.min(center - Math.floor(maxCharacters / 2), text.length - maxCharacters));
+  const previousLineBreak = proposedStart > 0 ? text.lastIndexOf("\n", proposedStart - 1) : -1;
+  const start = previousLineBreak >= 0 ? previousLineBreak + 1 : proposedStart;
+  const proposedEnd = Math.min(text.length, start + maxCharacters);
+  const previousEndLineBreak = proposedEnd < text.length ? text.lastIndexOf("\n", proposedEnd) : -1;
+  const end = previousEndLineBreak > start ? previousEndLineBreak + 1 : proposedEnd;
+  return text.slice(start, end);
+}

package/pi-extension/src/conversation-history/runtime.ts

@@ -0,0 +1,250 @@
+import { FreeflowContextRuntime } from "../freeflow-context/runtime.js";
+import { contextRefForEntry, entryIdFromContextRef } from "../freeflow-context/types.js";
+import type { FreeflowContextSnapshot, ProjectedContextSource } from "../freeflow-context/types.js";
+import { focusedWindow } from "./ranking.js";
+import { searchConversationEntries, type ConversationSearchOptions } from "./search.js";
+import { tokenize, unique } from "./passages.js";
+import type { ConversationSearchEntry } from "./types.js";
+
+const MAX_QUERY_CHARACTERS = 500;
+const MAX_QUERY_TERMS = 32;
+const MAX_TOOL_NAMES = 8;
+const MAX_TOOL_NAME_CHARACTERS = 128;
+const MAX_REF_CHARACTERS = 256;
+const MAX_FOCUS_CHARACTERS = 500;
+const MAX_RETRIEVE_REFS = 3;
+const MAX_SOURCE_CHARACTERS = 8_000;
+const MAX_TOTAL_RETRIEVED_CHARACTERS = 24_000;
+const VALID_KINDS = new Set(["user", "assistant", "toolResult", "summary"]);
+
+function normalizedTerms(value: string): string[] {
+  return unique(tokenize(value));
+}
+
+function failure(operation: "search" | "retrieve", reason: string, message?: string) {
+  return {
+    status: "rejected" as const,
+    operation,
+    reason: reason.slice(0, 64),
+    ...(message ? { message: message.slice(0, 500) } : {}),
+  };
+}
+
+function unavailable(operation: "search" | "retrieve", reason = "conversation_history_unavailable") {
+  return { status: "unavailable" as const, operation, reason: reason.slice(0, 64) };
+}
+
+function sourceMetadata(source: ProjectedContextSource) {
+  return {
+    ref: source.ref,
+    kind: source.kind,
+    ...(source.toolNames
+      ? {
+          toolNames: source.toolNames.slice(0, MAX_TOOL_NAMES),
+          ...(source.toolNames.length > MAX_TOOL_NAMES ? { toolNamesTruncated: true } : {}),
+        }
+      : {}),
+    ...(source.isError === undefined ? {} : { isError: source.isError }),
+    timestamp: source.timestamp.slice(0, 64),
+  };
+}
+
+export class ConversationHistoryRuntime {
+  private ctx: any;
+  private readonly freeflowContext: FreeflowContextRuntime;
+  private readonly isSourceFullyProjected: (entryId: string) => boolean;
+  private snapshot: FreeflowContextSnapshot | undefined;
+  private available = true;
+  private unavailableReason: string | undefined;
+
+  constructor(
+    ctx: any,
+    isSourceFullyProjected: (entryId: string) => boolean = () => true,
+    freeflowContext = new FreeflowContextRuntime(ctx),
+  ) {
+    this.ctx = ctx;
+    this.isSourceFullyProjected = isSourceFullyProjected;
+    this.freeflowContext = freeflowContext;
+  }
+
+  setContext(ctx: any): void {
+    this.ctx = ctx;
+    this.freeflowContext.setContext(ctx);
+  }
+
+  capture(contextVirtualizationEnabled = false): boolean {
+    try {
+      this.freeflowContext.setContext(this.ctx);
+      this.snapshot = this.freeflowContext.captureSnapshot({
+        contextVirtualizationEnabled,
+        isSourceFullyProjected: this.isSourceFullyProjected,
+      });
+      this.available = true;
+      this.unavailableReason = undefined;
+      return true;
+    } catch (error) {
+      this.snapshot = undefined;
+      this.available = false;
+      this.unavailableReason = error instanceof Error ? error.message : String(error);
+      return false;
+    }
+  }
+
+  async search(params: Record<string, unknown>, signal?: AbortSignal): Promise<any> {
+    if (signal?.aborted) return unavailable("search", "conversation_history_search_cancelled");
+    if (!this.available || !this.snapshot) return unavailable("search", this.unavailableReason);
+    const validation = this.validateSearch(params);
+    if (validation) return validation;
+
+    const query = (params.query as string).trim();
+    const hidden = [...this.snapshot.entries.values()].filter(
+      (entry) =>
+        !this.snapshot?.visibleSourceIds.has(entry.source.source.entryId) &&
+        !this.snapshot?.materializedSourceIds.has(entry.source.source.entryId),
+    );
+    if (hidden.length === 0) {
+      if (this.snapshot.skippedEntries === 0) return failure("search", "no_hidden_conversation_history");
+      return {
+        status: "ok",
+        operation: "search",
+        query,
+        coverage: "partial",
+        skippedEntries: this.snapshot.skippedEntries,
+        returned: 0,
+        truncated: false,
+        hits: [],
+      };
+    }
+
+    let result;
+    try {
+      result = searchConversationEntries(
+        hidden as ConversationSearchEntry[],
+        {
+          query,
+          kinds: params.kinds as ConversationSearchOptions["kinds"],
+          toolNames: Array.isArray(params.toolNames)
+            ? params.toolNames.map((name) => (typeof name === "string" ? name.trim() : ""))
+            : undefined,
+          limit: params.limit as number | undefined,
+        },
+        signal,
+      );
+    } catch (error) {
+      if (signal?.aborted || (error instanceof Error && error.name === "AbortError")) {
+        return unavailable("search", "conversation_history_search_cancelled");
+      }
+      return unavailable("search");
+    }
+    return {
+      status: "ok",
+      operation: "search",
+      query,
+      coverage: this.snapshot.skippedEntries > 0 ? "partial" : "complete",
+      ...(this.snapshot.skippedEntries > 0 ? { skippedEntries: this.snapshot.skippedEntries } : {}),
+      returned: result.returned,
+      truncated: result.truncated,
+      hits: result.hits,
+    };
+  }
+
+  async retrieve(params: Record<string, unknown>, signal?: AbortSignal): Promise<any> {
+    if (signal?.aborted) return unavailable("retrieve", "conversation_history_retrieve_cancelled");
+    if (!this.available || !this.snapshot) return unavailable("retrieve", this.unavailableReason);
+    const refs = params.refs;
+    if (!Array.isArray(refs) || refs.length < 1 || refs.length > MAX_RETRIEVE_REFS) {
+      return failure("retrieve", "refs_count_invalid");
+    }
+    if (refs.some((ref) => typeof ref !== "string" || ref.length > MAX_REF_CHARACTERS)) {
+      return failure("retrieve", "ref_invalid");
+    }
+    const canonicalRefs = refs.map((ref) => {
+      const entryId = entryIdFromContextRef(ref);
+      return entryId ? contextRefForEntry(entryId) : undefined;
+    });
+    if (canonicalRefs.some((ref) => ref === undefined)) return failure("retrieve", "ref_invalid");
+    const uniqueRefs = canonicalRefs as string[];
+    if (new Set(uniqueRefs).size !== uniqueRefs.length) return failure("retrieve", "duplicate_ref");
+    const focus = params.focus;
+    if (
+      focus !== undefined &&
+      (typeof focus !== "string" || focus.trim().length === 0 || focus.length > MAX_FOCUS_CHARACTERS)
+    ) {
+      return failure("retrieve", "focus_invalid");
+    }
+
+    const items = [];
+    let total = 0;
+    for (const ref of uniqueRefs) {
+      if (signal?.aborted) return unavailable("retrieve", "conversation_history_retrieve_cancelled");
+      const entryId = entryIdFromContextRef(ref);
+      const source = entryId ? this.snapshot.entries.get(contextRefForEntry(entryId)) : undefined;
+      if (!source) return failure("retrieve", "reference_unresolved");
+      if (this.snapshot.visibleSourceIds.has(entryId) || this.snapshot.materializedSourceIds.has(entryId)) {
+        return failure("retrieve", "source_visible");
+      }
+      const sourceCharacters = source.text.length;
+      let content = source.text;
+      let completeness: "complete" | "partial" = "complete";
+      if (sourceCharacters > MAX_SOURCE_CHARACTERS) {
+        if (typeof focus !== "string") return failure("retrieve", "focus_required_for_oversized_source");
+        const focused = focusedWindow(source.text, focus.trim(), MAX_SOURCE_CHARACTERS);
+        if (focused === undefined) return failure("retrieve", "focus_no_match");
+        content = focused;
+        completeness = "partial";
+      }
+      if (total + content.length > MAX_TOTAL_RETRIEVED_CHARACTERS)
+        return failure("retrieve", "retrieval_budget_exceeded");
+      total += content.length;
+      items.push({
+        ...sourceMetadata(source),
+        content,
+        completeness,
+        sourceCharacters,
+        returnedCharacters: content.length,
+      });
+    }
+    return {
+      status: "ok",
+      operation: "retrieve",
+      ...(typeof focus === "string" ? { focus: focus.trim() } : {}),
+      items,
+    };
+  }
+
+  private validateSearch(params: Record<string, unknown>): any | undefined {
+    if (typeof params.query !== "string" || params.query.trim().length === 0)
+      return failure("search", "query_required");
+    if (params.query.length > MAX_QUERY_CHARACTERS) return failure("search", "query_too_long");
+    if (normalizedTerms(params.query).length > MAX_QUERY_TERMS) return failure("search", "query_terms_too_many");
+    if (params.kinds !== undefined) {
+      if (!Array.isArray(params.kinds) || params.kinds.length < 1 || params.kinds.length > 4)
+        return failure("search", "kinds_invalid");
+      if (
+        new Set(params.kinds).size !== params.kinds.length ||
+        params.kinds.some((kind) => typeof kind !== "string" || !VALID_KINDS.has(kind))
+      ) {
+        return failure("search", "kinds_invalid");
+      }
+    }
+    if (params.toolNames !== undefined) {
+      if (!Array.isArray(params.toolNames) || params.toolNames.length < 1 || params.toolNames.length > MAX_TOOL_NAMES)
+        return failure("search", "tool_names_invalid");
+      const normalizedNames = params.toolNames.map((name) => (typeof name === "string" ? name.trim() : ""));
+      if (
+        params.toolNames.some((name) => typeof name !== "string") ||
+        new Set(normalizedNames.map((name) => name.toLocaleLowerCase())).size !== normalizedNames.length ||
+        normalizedNames.some((name) => name.length === 0 || name.length > MAX_TOOL_NAME_CHARACTERS)
+      ) {
+        return failure("search", "tool_names_invalid");
+      }
+    }
+    if (
+      params.limit !== undefined &&
+      (!Number.isInteger(params.limit) || (params.limit as number) < 1 || (params.limit as number) > 20)
+    ) {
+      return failure("search", "limit_invalid");
+    }
+    return undefined;
+  }
+}

package/pi-extension/src/conversation-history/search.ts

@@ -0,0 +1,79 @@
+import { normalizeText, snippet, throwIfAborted, tokenize, unique } from "./passages.js";
+import { rankMatchingPassages } from "./ranking.js";
+import type {
+  ConversationSearchEntry,
+  ConversationSearchHit,
+  ConversationSearchOptions,
+  ConversationSearchResult,
+} from "./types.js";
+
+export type {
+  ConversationSearchEntry,
+  ConversationSearchHit,
+  ConversationSearchOptions,
+  ConversationSearchResult,
+} from "./types.js";
+
+const MAX_DISPLAYED_TOOL_NAMES = 8;
+
+function matchesFilters(entry: ConversationSearchEntry, options: ConversationSearchOptions): boolean {
+  if (options.kinds && !options.kinds.includes(entry.kind)) return false;
+  if (options.toolNames) {
+    const names = new Set((entry.toolNames ?? []).map((name) => name.toLocaleLowerCase()));
+    if (!options.toolNames.some((name) => names.has(name.toLocaleLowerCase()))) return false;
+  }
+  return true;
+}
+
+export function searchConversationEntries(
+  entries: readonly ConversationSearchEntry[],
+  options: ConversationSearchOptions,
+  signal?: AbortSignal,
+): ConversationSearchResult {
+  throwIfAborted(signal);
+  const normalizedQuery = normalizeText(options.query);
+  const terms = unique(tokenize(options.query));
+  const limit = Math.min(20, Math.max(1, Math.trunc(options.limit ?? 8)));
+  if (!normalizedQuery || terms.length === 0) return { returned: 0, truncated: false, hits: [] };
+
+  const candidates = entries.filter((entry) => matchesFilters(entry, options));
+  const rankedPassages = rankMatchingPassages(candidates, options.query, signal);
+  const byEntry = new Map<string, (typeof rankedPassages)[number]>();
+  for (const passage of rankedPassages) {
+    throwIfAborted(signal);
+    if (!byEntry.has(passage.entry.ref)) byEntry.set(passage.entry.ref, passage);
+  }
+
+  const ranked = [...byEntry.values()];
+  const hits = ranked.slice(0, limit).map((passage) => {
+    const matchType = passage.exactPhrase
+      ? "exact-phrase"
+      : passage.matchedTerms.length === terms.length
+        ? "all-terms"
+        : "partial-terms";
+    return {
+      ref: passage.entry.ref,
+      kind: passage.entry.kind,
+      ...(passage.entry.toolNames
+        ? {
+            toolNames: passage.entry.toolNames.slice(0, MAX_DISPLAYED_TOOL_NAMES),
+            ...(passage.entry.toolNames.length > MAX_DISPLAYED_TOOL_NAMES ? { toolNamesTruncated: true } : {}),
+          }
+        : {}),
+      ...(passage.entry.isError === undefined ? {} : { isError: passage.entry.isError }),
+      timestamp: passage.entry.timestamp.slice(0, 64),
+      snippet: snippet(passage.passage.text, normalizedQuery, terms),
+      match: {
+        type: matchType,
+        matchedTerms: passage.matchedTerms,
+        queryTermCount: terms.length,
+      },
+    } satisfies ConversationSearchHit;
+  });
+
+  return {
+    returned: hits.length,
+    truncated: ranked.length > limit,
+    hits,
+  };
+}

package/pi-extension/src/conversation-history/types.ts

@@ -0,0 +1,31 @@
+import type { ProjectedContextSource } from "../freeflow-context/types.js";
+
+export type ConversationSearchEntry = ProjectedContextSource;
+
+export type ConversationSearchOptions = {
+  query: string;
+  kinds?: readonly ConversationSearchEntry["kind"][];
+  toolNames?: readonly string[];
+  limit?: number;
+};
+
+export type ConversationSearchHit = {
+  ref: string;
+  kind: ConversationSearchEntry["kind"];
+  toolNames?: string[];
+  toolNamesTruncated?: boolean;
+  isError?: boolean;
+  timestamp: string;
+  snippet: string;
+  match: {
+    type: "exact-phrase" | "all-terms" | "partial-terms";
+    matchedTerms: string[];
+    queryTermCount: number;
+  };
+};
+
+export type ConversationSearchResult = {
+  returned: number;
+  truncated: boolean;
+  hits: ConversationSearchHit[];
+};