@hassangameryt/freeflow 0.5.0 → 0.7.0

package/pi-extension/dist/context-virtualization/projector.js

@@ -0,0 +1,42 @@
+import { CONTEXT_REF_PREFIX, contextRefForEntry } from "./types.js";
+export function contentCharacters(content) {
+  if (typeof content === "string") return content.length;
+  if (!Array.isArray(content)) return 0;
+  return content.reduce((total, part) => {
+    if (part?.type === "text" && typeof part.text === "string") return total + part.text.length;
+    if (part?.type === "image") return total + 16;
+    return total;
+  }, 0);
+}
+export function contextMarker(source) {
+  return {
+    type: "text",
+    text: `[context-ref: ${contextRefForEntry(source.entryId)}]`,
+  };
+}
+export function archiveContent(source, retained) {
+  const marker = `[context archived: ${contextRefForEntry(source.entryId)}]`;
+  if (!retained) return marker;
+  return `${marker}\n\n<retained-context>\n${retained}\n</retained-context>`;
+}
+export function fullContent(source, content = []) {
+  return [...content, contextMarker(source)];
+}
+export function projectedContent(source, content, projection) {
+  if (projection.mode === "archived") {
+    return [{ type: "text", text: archiveContent(source, projection.retained) }];
+  }
+  return fullContent(source, Array.isArray(content) ? content : [{ type: "text", text: String(content ?? "") }]);
+}
+export function projectToolResultMessage(message, source, projection) {
+  return {
+    ...message,
+    content: projectedContent(source, message.content, projection),
+  };
+}
+export function projectedCharacters(source, message, projection) {
+  return contentCharacters(projectedContent(source, message?.content, projection));
+}
+export function sourceReference(source) {
+  return `${CONTEXT_REF_PREFIX}${source.entryId}`;
+}

package/pi-extension/dist/context-virtualization/runtime.js

@@ -0,0 +1,356 @@
+import {
+  CONTEXT_PROJECTION_ENTRY,
+  CONTEXT_PROJECTION_VERSION,
+  contextRefForEntry,
+  entryIdFromContextRef,
+} from "./types.js";
+import { FreeflowContextRuntime } from "../freeflow-context/runtime.js";
+import { contentCharacters, projectToolResultMessage, projectedCharacters } from "./projector.js";
+import { replayProjectionEntries } from "./state.js";
+function cloneSource(source) {
+  return { ...source };
+}
+function sourceProjection(state) {
+  if (!state || state.mode === "full") return { mode: "full" };
+  return state.retained === undefined ? { mode: "archived" } : { mode: "archived", retained: state.retained };
+}
+function safeJsonEqual(left, right) {
+  try {
+    return JSON.stringify(left) === JSON.stringify(right);
+  } catch {
+    return false;
+  }
+}
+function isDuplicate(values) {
+  const seen = new Set();
+  for (const value of values) {
+    if (seen.has(value)) return value;
+    seen.add(value);
+  }
+  return undefined;
+}
+export class ContextVirtualizationRuntime {
+  pi;
+  freeflowContext;
+  ctx;
+  sessionId = "current";
+  branchLeafId;
+  projectionState = new Map();
+  available = true;
+  unavailableReason;
+  mutationQueue = Promise.resolve();
+  constructor(pi, ctx, freeflowContext = new FreeflowContextRuntime(ctx)) {
+    this.pi = pi;
+    this.ctx = ctx;
+    this.freeflowContext = freeflowContext;
+  }
+  setContext(ctx) {
+    this.ctx = ctx;
+    this.freeflowContext.setContext(ctx);
+  }
+  async recover(ctx = this.ctx, options = {}) {
+    this.ctx = ctx;
+    this.freeflowContext.setContext(ctx);
+    try {
+      this.sessionId = this.freeflowContext.sessionId();
+      this.branchLeafId = this.freeflowContext.branchLeafId();
+      this.projectionState = replayProjectionEntries(this.freeflowContext.branchEntries(), this.sessionId);
+      if (!options.preserveRequest) this.freeflowContext.clearRequest();
+      this.available = true;
+      this.unavailableReason = undefined;
+      return true;
+    } catch (error) {
+      this.available = false;
+      this.unavailableReason = error instanceof Error ? error.message : String(error);
+      this.freeflowContext.clearRequest();
+      return false;
+    }
+  }
+  isAvailable() {
+    return this.available;
+  }
+  isSourceFullyProjected(entryId) {
+    if (!this.available) return true;
+    const projection = this.projectionState.get(entryId);
+    return !projection || projection.mode === "full";
+  }
+  async project(messages, enabled) {
+    if (!enabled) {
+      this.freeflowContext.clearRequest();
+      return { messages, changed: false, available: true };
+    }
+    if (!(await this.recover(this.ctx))) {
+      return { messages, changed: false, available: false };
+    }
+    const sourcesByToolCallId = this.freeflowContext.resolver.toolResultSources();
+    const refs = new Map();
+    let changed = false;
+    const projected = messages.map((message) => {
+      if (message?.role !== "toolResult" || typeof message.toolCallId !== "string") return message;
+      const source = sourcesByToolCallId.get(message.toolCallId);
+      if (!source) return message;
+      const ref = contextRefForEntry(source.source.entryId);
+      refs.set(ref, source);
+      const state = this.projectionState.get(source.source.entryId);
+      const projection = sourceProjection(state);
+      const nextMessage = projectToolResultMessage(message, source.source, projection);
+      if (!safeJsonEqual(nextMessage.content, message.content)) changed = true;
+      return nextMessage;
+    });
+    const request = this.freeflowContext.recordRequest(refs);
+    return {
+      messages: changed ? projected : messages,
+      changed,
+      available: true,
+      generation: request.generation,
+    };
+  }
+  async archive(targets) {
+    try {
+      return await this.enqueue(() => this.archiveNow(targets));
+    } catch (error) {
+      return this.rejected("archive", `persistence_failed:${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  async restore(refs, actor = "model") {
+    try {
+      return await this.enqueue(() => this.restoreNow(refs, actor));
+    } catch (error) {
+      return this.rejected("restore", `persistence_failed:${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  async reset() {
+    try {
+      return await this.enqueue(async () => {
+        if (!this.available) return this.unavailable("reset");
+        const journal = {
+          version: CONTEXT_PROJECTION_VERSION,
+          actor: "user",
+          reset: "all",
+        };
+        await this.persist(journal);
+        this.projectionState.clear();
+        return {
+          status: "ok",
+          operation: "reset",
+          changed: ["all"],
+          message: "All context projection decisions were reset on the active branch.",
+        };
+      });
+    } catch (error) {
+      return this.rejected("reset", `persistence_failed:${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  async status(limit = 50) {
+    if (!this.available) {
+      return {
+        available: false,
+        unavailableReason: this.unavailableReason,
+        sessionId: this.sessionId,
+        branchLeafId: this.branchLeafId,
+        counts: { full: 0, archived: 0, retained: 0 },
+        originalCharacters: 0,
+        projectedCharacters: 0,
+        historyOnly: 0,
+        unresolved: 0,
+        items: [],
+      };
+    }
+    if (!(await this.recover(this.ctx, { preserveRequest: true }))) {
+      return this.status(limit);
+    }
+    const branchSources = this.freeflowContext.resolver.sourcesByEntryId();
+    const activeIds = this.freeflowContext.resolver.activeToolResultIds();
+    const items = [];
+    for (const source of branchSources.values()) {
+      const state = this.projectionState.get(source.source.entryId);
+      const projection = sourceProjection(state);
+      items.push(this.listItem(source, projection, activeIds.has(source.source.entryId) ? "active" : "history-only"));
+    }
+    for (const state of this.projectionState.values()) {
+      if (branchSources.has(state.source.entryId)) continue;
+      const projection = sourceProjection(state);
+      items.push({
+        ref: contextRefForEntry(state.source.entryId),
+        entryId: state.source.entryId,
+        toolCallId: state.source.toolCallId,
+        toolName: state.source.toolName,
+        mode: projection.mode,
+        ...(projection.mode === "archived" && projection.retained !== undefined
+          ? { retained: projection.retained }
+          : {}),
+        originalCharacters: 0,
+        projectedCharacters: projection.mode === "archived" ? contentCharacters(projection.retained ?? "") : 0,
+        availability: "unresolved",
+      });
+    }
+    const counts = { full: 0, archived: 0, retained: 0 };
+    let originalCharacters = 0;
+    let projectedCharactersTotal = 0;
+    let historyOnly = 0;
+    let unresolved = 0;
+    for (const item of items) {
+      if (item.mode === "full") counts.full += 1;
+      else {
+        counts.archived += 1;
+        if (item.retained !== undefined) counts.retained += 1;
+      }
+      originalCharacters += item.originalCharacters;
+      projectedCharactersTotal += item.projectedCharacters;
+      if (item.availability === "history-only") historyOnly += 1;
+      if (item.availability === "unresolved") unresolved += 1;
+    }
+    return {
+      available: true,
+      sessionId: this.sessionId,
+      branchLeafId: this.branchLeafId,
+      counts,
+      originalCharacters,
+      projectedCharacters: projectedCharactersTotal,
+      historyOnly,
+      unresolved,
+      items: items.slice(-Math.max(1, limit)),
+    };
+  }
+  async archiveNow(targets) {
+    if (!this.available) return this.unavailable("archive");
+    if (!Array.isArray(targets) || targets.length === 0) {
+      return this.rejected("archive", "targets_required");
+    }
+    const normalizedRefs = targets.map((target) =>
+      target && typeof target === "object" ? entryIdFromContextRef(target.ref) : undefined,
+    );
+    const duplicate = isDuplicate(
+      normalizedRefs.flatMap((ref) => (ref === undefined ? [] : [contextRefForEntry(ref)])),
+    );
+    if (duplicate) return this.rejected("archive", `duplicate_reference:${duplicate}`);
+    const latestRequest = this.freeflowContext.latestRequest();
+    if (!latestRequest) return this.rejected("archive", "no_consumed_context_request");
+    const changes = [];
+    const retainedMeaning = {};
+    for (let index = 0; index < targets.length; index += 1) {
+      const target = targets[index];
+      if (!target || typeof target !== "object") return this.rejected("archive", `target_${index}_must_be_object`);
+      const ref = normalizedRefs[index];
+      if (!ref) return this.rejected("archive", `target_${index}_invalid_reference`);
+      const normalizedRef = contextRefForEntry(ref);
+      const source = latestRequest.refs.get(normalizedRef);
+      if (!source) return this.rejected("archive", `target_not_in_consumed_context:${normalizedRef}`);
+      const retainedValue = target.retained;
+      if (retainedValue !== undefined && (typeof retainedValue !== "string" || retainedValue.trim() === "")) {
+        return this.rejected("archive", `target_${index}_retained_must_be_non_empty`);
+      }
+      const retained = typeof retainedValue === "string" ? retainedValue.trim() : undefined;
+      changes.push({
+        source: cloneSource(source.source),
+        projection: retained === undefined ? { mode: "archived" } : { mode: "archived", retained },
+      });
+      if (retained !== undefined) retainedMeaning[normalizedRef] = retained;
+    }
+    await this.persist({ version: CONTEXT_PROJECTION_VERSION, actor: "model", changes });
+    for (const change of changes) {
+      this.projectionState.set(change.source.entryId, {
+        source: cloneSource(change.source),
+        ...change.projection,
+      });
+    }
+    return {
+      status: "ok",
+      operation: "archive",
+      changed: changes.map((change) => contextRefForEntry(change.source.entryId)),
+      message: `Archived ${changes.length} tool result${changes.length === 1 ? "" : "s"} from future context projections.`,
+      ...(Object.keys(retainedMeaning).length > 0 ? { retained: retainedMeaning } : {}),
+    };
+  }
+  async restoreNow(refs, actor) {
+    if (!this.available) return this.unavailable("restore");
+    if (!Array.isArray(refs) || refs.length === 0) return this.rejected("restore", "refs_required");
+    const normalizedRefs = refs.map((ref) => entryIdFromContextRef(ref));
+    const duplicate = isDuplicate(
+      normalizedRefs.flatMap((ref) => (ref === undefined ? [] : [contextRefForEntry(ref)])),
+    );
+    if (duplicate) return this.rejected("restore", `duplicate_reference:${duplicate}`);
+    const changes = [];
+    const availability = {};
+    const activeIds = this.freeflowContext.resolver.activeToolResultIds();
+    const latestRequest = this.freeflowContext.latestRequest();
+    for (let index = 0; index < refs.length; index += 1) {
+      const ref = normalizedRefs[index];
+      if (!ref) return this.rejected("restore", `ref_${index}_invalid_reference`);
+      const normalizedRef = contextRefForEntry(ref);
+      const current = this.projectionState.get(ref);
+      if (!current) return this.rejected("restore", `reference_not_archived:${normalizedRef}`);
+      if (actor === "model" && !latestRequest?.refs.has(normalizedRef)) {
+        return this.rejected("restore", `target_not_in_consumed_context:${normalizedRef}`);
+      }
+      changes.push({ source: cloneSource(current.source), projection: { mode: "full" } });
+      let availabilityValue;
+      if (latestRequest?.refs.has(normalizedRef) || activeIds.has(current.source.entryId)) {
+        availabilityValue = "active";
+      } else {
+        availabilityValue = "history-only";
+      }
+      availability[normalizedRef] = availabilityValue;
+    }
+    await this.persist({ version: CONTEXT_PROJECTION_VERSION, actor, changes });
+    for (const change of changes) {
+      this.projectionState.set(change.source.entryId, {
+        source: cloneSource(change.source),
+        mode: "full",
+      });
+    }
+    return {
+      status: "ok",
+      operation: "restore",
+      changed: changes.map((change) => contextRefForEntry(change.source.entryId)),
+      availability,
+      message: `Restored ${changes.length} projection${changes.length === 1 ? "" : "s"} to full content.`,
+    };
+  }
+  listItem(source, projection, availability) {
+    const item = {
+      ref: contextRefForEntry(source.source.entryId),
+      entryId: source.source.entryId,
+      toolCallId: source.source.toolCallId,
+      toolName: source.source.toolName,
+      mode: projection.mode,
+      originalCharacters: contentCharacters(source.message?.content),
+      projectedCharacters: projectedCharacters(source.source, source.message, projection),
+      availability,
+    };
+    if (projection.mode === "archived" && projection.retained !== undefined) {
+      item.retained = projection.retained;
+    }
+    return item;
+  }
+  rejected(operation, message) {
+    return { status: "rejected", operation, changed: [], message };
+  }
+  unavailable(operation) {
+    return {
+      status: "unavailable",
+      operation,
+      changed: [],
+      message: this.unavailableReason ?? "context_virtualization_unavailable",
+    };
+  }
+  persist(journal) {
+    let append;
+    if (typeof this.pi?.appendEntryDurable === "function") {
+      append = this.pi.appendEntryDurable;
+    } else if (typeof this.pi?.appendEntry === "function") {
+      append = this.pi.appendEntry;
+    }
+    if (!append) throw new Error("The Pi host does not expose a session entry persistence method.");
+    const result = append.call(this.pi, CONTEXT_PROJECTION_ENTRY, journal);
+    if (result && typeof result.then === "function") return result;
+  }
+  enqueue(task) {
+    const run = this.mutationQueue.then(task);
+    this.mutationQueue = run.then(
+      () => undefined,
+      () => undefined,
+    );
+    return run;
+  }
+}

package/pi-extension/dist/context-virtualization/state.js

@@ -0,0 +1,57 @@
+import { CONTEXT_PROJECTION_ENTRY, CONTEXT_PROJECTION_VERSION, isRecord } from "./types.js";
+function isProjection(value) {
+  if (!isRecord(value) || (value.mode !== "full" && value.mode !== "archived")) return false;
+  if (value.mode === "archived" && value.retained !== undefined && typeof value.retained !== "string") return false;
+  return true;
+}
+function isJournal(value) {
+  if (!isRecord(value) || value.version !== CONTEXT_PROJECTION_VERSION) return false;
+  if (value.actor !== "model" && value.actor !== "user") return false;
+  if (value.reset !== undefined && value.reset !== "all") return false;
+  if (value.changes !== undefined && !Array.isArray(value.changes)) return false;
+  return true;
+}
+export function replayProjectionEntries(entries, sessionId) {
+  const state = new Map();
+  for (const entry of entries) {
+    if (entry?.type !== "custom" || entry.customType !== CONTEXT_PROJECTION_ENTRY) continue;
+    const data = entry.data;
+    if (!isJournal(data)) continue;
+    if (data.reset === "all") {
+      state.clear();
+    }
+    for (const change of data.changes ?? []) {
+      if (!isRecord(change) || !isRecord(change.source) || !isProjection(change.projection)) continue;
+      if (change.source.sessionId !== sessionId || typeof change.source.entryId !== "string") continue;
+      if (change.projection.mode === "archived" && change.projection.retained !== undefined) {
+        state.set(change.source.entryId, {
+          source: { ...change.source },
+          mode: "archived",
+          retained: change.projection.retained,
+        });
+      } else if (change.projection.mode === "archived") {
+        state.set(change.source.entryId, {
+          source: { ...change.source },
+          mode: "archived",
+        });
+      } else {
+        state.set(change.source.entryId, {
+          source: { ...change.source },
+          mode: "full",
+        });
+      }
+    }
+  }
+  return state;
+}
+export function cloneProjectionState(state) {
+  return new Map(
+    [...state.entries()].map(([entryId, projection]) => [
+      entryId,
+      {
+        ...projection,
+        source: { ...projection.source },
+      },
+    ]),
+  );
+}

package/pi-extension/dist/context-virtualization/types.js

@@ -0,0 +1,10 @@
+export { CONTEXT_REF_PREFIX, contextRefForEntry, entryIdFromContextRef } from "../freeflow-context/types.js";
+export const CONTEXT_PROJECTION_ENTRY = "freeflow-context-projection";
+export const CONTEXT_PROJECTION_VERSION = 1;
+export function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function projectionCharacters(projection) {
+  if (projection.mode === "full") return 0;
+  return projection.retained?.length ?? 0;
+}

package/pi-extension/dist/conversation-history/passages.js

@@ -0,0 +1,66 @@
+export const PASSAGE_TARGET_CHARACTERS = 2_000;
+export const PASSAGE_OVERLAP_CHARACTERS = 200;
+export const SNIPPET_MAX_CHARACTERS = 400;
+export function normalizeText(value) {
+  return value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/g, " ").trim();
+}
+export function tokenize(value) {
+  return normalizeText(value).match(/[\p{L}\p{N}_]+(?:[./:@#$%+-][\p{L}\p{N}_]+)*/gu) ?? [];
+}
+export function unique(values) {
+  return [...new Set(values)];
+}
+export function throwIfAborted(signal) {
+  if (!signal?.aborted) return;
+  const error = new Error("conversation_history_search_cancelled");
+  error.name = "AbortError";
+  throw error;
+}
+function passageEnd(text, start) {
+  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, signal) {
+  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 = [];
+  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, phrase, terms) {
+  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/dist/conversation-history/ranking.js

@@ -0,0 +1,105 @@
+import { normalizeText, splitTextIntoPassages, throwIfAborted, tokenize, unique } from "./passages.js";
+export const BM25_K1 = 1.2;
+export const BM25_B = 0.75;
+function bm25Score(tokens, terms, documentFrequency, documentCount, averageLength) {
+  const counts = new Map();
+  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, right) {
+  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, right) {
+  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(inputs, terms, signal) {
+  const documentFrequency = new Map();
+  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 = [];
+  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 }, { ...right, entry: right.entry });
+      }
+      return compareTextPassages(left, right);
+    });
+}
+export function rankMatchingPassages(entries, query, signal) {
+  throwIfAborted(signal);
+  const normalizedQuery = normalizeText(query);
+  const terms = unique(tokenize(query));
+  if (!normalizedQuery || terms.length === 0) return [];
+  const inputs = [];
+  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);
+}
+export function strongestTextPassage(text, query) {
+  const normalizedQuery = normalizeText(query);
+  const terms = unique(tokenize(query));
+  if (!normalizedQuery || terms.length === 0) return undefined;
+  const inputs = splitTextIntoPassages(text).map((passage) => ({
+    passage,
+    exactPhrase: normalizeText(passage.text).includes(normalizedQuery),
+    matchedTerms: terms.filter((term) => passage.tokens.includes(term)),
+  }));
+  return rankInputs(inputs, terms)[0];
+}
+export function focusedWindow(text, focus, maxCharacters) {
+  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);
+}