@herbertgao/pi-extensions 2026.9.5 → 2026.9.7

package/node_modules/@luxusai/pi-hindsight/extensions/lifecycle/recall.ts

@@ -1,331 +0,0 @@
-import { basename } from "node:path";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import {
-  RECALL_SCORE_FIELDS,
-  type HindsightLikeClient,
-  type HindsightTagGroup,
-  type RecallBlock,
-  type RecallFailure,
-  type RecallMinScores,
-  type RecallResultItem,
-  type RecallRole,
-  type ResolvedConfig,
-} from "../types.js";
-import { isInjectedHindsightMemory, projectMessageText } from "../utils/messages.js";
-import { createMemoryIdentity } from "../operations/memory-identity.js";
-import { redactError } from "../utils/sanitize.js";
-import { withTimeout } from "../client/timeout.js";
-import { loadMentalModelsForScopes } from "./mental-models.js";
-
-export interface RecallScope {
-  kind?: "project" | "global";
-  bankId: string;
-  tagGroups?: HindsightTagGroup[];
-}
-
-function sourceFactText(value: unknown): string | undefined {
-  if (!value || typeof value !== "object") return undefined;
-  const text = (value as { text?: unknown }).text;
-  return typeof text === "string" && text.trim() ? text : undefined;
-}
-
-function textFromRecallResponse(response: unknown): RecallResultItem[] {
-  const record = response as Record<string, unknown>;
-  const raw = Array.isArray(record.results)
-    ? record.results
-    : Array.isArray(record.memories)
-      ? record.memories
-      : Array.isArray(response)
-        ? response
-        : [];
-  const sourceFacts =
-    record.source_facts && typeof record.source_facts === "object"
-      ? (record.source_facts as Record<string, unknown>)
-      : undefined;
-  return raw.map((entry) => {
-    const item = entry as RecallResultItem;
-    if (!sourceFacts || !item.source_fact_ids?.length) return item;
-    const evidence = item.source_fact_ids
-      .map((id) => sourceFactText(sourceFacts[id]))
-      .filter((text): text is string => Boolean(text));
-    return evidence.length ? { ...item, sourceFacts: evidence } : item;
-  });
-}
-
-function itemText(item: RecallResultItem): string {
-  return item.text ?? item.content ?? JSON.stringify(item);
-}
-
-export interface RecallQueryPolicy {
-  roles: RecallRole[];
-  contextTurns: number;
-  maxQueryChars: number;
-  preamble?: string;
-  includeDate?: boolean;
-  now?: Date;
-  hints?: string[];
-}
-
-function messageRole(message: AgentMessage): string {
-  return (message as unknown as { role?: string }).role ?? "unknown";
-}
-
-function messageContent(message: AgentMessage): string {
-  const content = projectMessageText(message).content;
-  return typeof content === "string" ? content : JSON.stringify(content ?? "");
-}
-
-function formatQueryMessage(message: AgentMessage): string | undefined {
-  const content = messageContent(message).trim();
-  return content ? `${messageRole(message)}: ${content}` : undefined;
-}
-
-export function truncateRecallQuery(query: string, maxChars: number): string {
-  if (query.length <= maxChars) return query;
-  return query.slice(query.length - maxChars).trimStart();
-}
-
-function truncateRecallQueryLines(
-  prefixLines: string[],
-  messageLines: string[],
-  maxChars: number,
-): string {
-  const lines = [...prefixLines, ...messageLines];
-  const query = lines.join("\n\n").trim();
-  if (query.length <= maxChars) return query;
-  const prefix = prefixLines.join("\n\n").trim();
-  if (!prefix) return truncateRecallQuery(query, maxChars);
-  const separator = "\n\n";
-  const remaining = maxChars - prefix.length - separator.length;
-  if (remaining >= 20)
-    return `${prefix}${separator}${truncateRecallQuery(messageLines.join("\n\n"), remaining)}`;
-  return truncateRecallQuery(query, maxChars);
-}
-
-export function composeRecallQuery(messages: AgentMessage[], policy: RecallQueryPolicy): string {
-  const allowedRoles = new Set<string>(policy.roles);
-  const selectedLines = messages
-    .filter((message) => allowedRoles.has(messageRole(message)))
-    .filter((message) => !isInjectedHindsightMemory(message))
-    .map(formatQueryMessage)
-    .filter((line): line is string => Boolean(line))
-    .slice(-Math.max(1, policy.contextTurns));
-  const prefixLines = [
-    ...(policy.preamble?.trim() ? [policy.preamble.trim()] : []),
-    ...(policy.includeDate
-      ? [`Current date: ${(policy.now ?? new Date()).toISOString().slice(0, 10)}`]
-      : []),
-    ...(policy.hints?.length ? [`Context hints: ${policy.hints.join("; ")}`] : []),
-  ];
-  return truncateRecallQueryLines(
-    prefixLines,
-    selectedLines.length ? selectedLines : ["current Pi coding task"],
-    policy.maxQueryChars,
-  );
-}
-
-const RECALL_SOURCE_FACT_LINES = 3;
-
-export function renderRecallBlocks(blocks: RecallBlock[], topK = 12): string {
-  const nonEmpty = blocks.filter((block) => block.memoryCount > 0);
-  if (nonEmpty.length === 0) return "";
-  const lines = [
-    "<hindsight-memory>",
-    "Relevant prior memory. Use as context; do not quote unless useful.",
-  ];
-  for (const block of nonEmpty) {
-    lines.push(`\nBank: ${block.bankId}`);
-    block.results.slice(0, topK).forEach((item, index) => {
-      const tags = item.tags?.length ? ` [${item.tags.join(", ")}]` : "";
-      lines.push(`${index + 1}. ${itemText(item)}${tags}`);
-      for (const fact of (item.sourceFacts ?? []).slice(0, RECALL_SOURCE_FACT_LINES)) {
-        lines.push(`   - evidence: ${fact}`);
-      }
-    });
-  }
-  lines.push("</hindsight-memory>");
-  return lines.join("\n");
-}
-
-function preambleForScope(config: ResolvedConfig, scope: RecallScope): string {
-  if (scope.kind === "project") return config.recall.projectQueryPreamble;
-  if (scope.kind === "global") return config.recall.globalQueryPreamble;
-  return config.recall.queryPreamble;
-}
-
-// User Bank recall is a smaller, durable supplement to project context, not an equal-weight
-// second corpus, so it gets its own (smaller by default) token budget. Project Bank recall
-// keeps recall.maxTokens unchanged so single-scope callers see no behavior change.
-function maxTokensForScope(config: ResolvedConfig, scope: RecallScope): number {
-  return scope.kind === "global" ? config.recall.userMaxTokens : config.recall.maxTokens;
-}
-
-function queryHints(cwd: string, config: ResolvedConfig, scope: RecallScope): string[] {
-  const hints = scope.kind ? [`scope:${scope.kind}`] : [];
-  if (!config.recall.includeRepoHintsInQuery || scope.kind === "global") return hints;
-  const identity = createMemoryIdentity(cwd, config);
-  return [
-    ...hints,
-    `project:${identity.projectId}`,
-    `repo:${identity.repoKey}`,
-    `cwd:${basename(cwd)}`,
-  ];
-}
-
-export async function recallForContext(args: {
-  client: HindsightLikeClient;
-  config: ResolvedConfig;
-  scopes: RecallScope[];
-  messages: AgentMessage[];
-  cwd?: string;
-}): Promise<{
-  rendered: string;
-  blocks: RecallBlock[];
-  failed: number;
-  failures: RecallFailure[];
-}> {
-  const blocks: RecallBlock[] = [];
-  const failures: RecallFailure[] = [];
-  for (const scope of args.scopes) {
-    const query = composeRecallQuery(args.messages, {
-      roles: args.config.recall.roles,
-      contextTurns: args.config.recall.contextTurns,
-      maxQueryChars: args.config.recall.maxQueryChars,
-      preamble: preambleForScope(args.config, scope),
-      includeDate: args.config.recall.includeDateInQuery,
-      hints: args.cwd ? queryHints(args.cwd, args.config, scope) : [],
-    });
-    try {
-      const response = await withTimeout("hindsight recall", args.config.recall.timeoutMs, () =>
-        args.client.recall(scope.bankId, query, {
-          budget: args.config.recall.budget,
-          maxTokens: maxTokensForScope(args.config, scope),
-          types: args.config.recall.types,
-          preferObservations: args.config.recall.preferObservations,
-          ...(args.config.recall.includeSourceFacts
-            ? {
-                includeSourceFacts: true,
-                maxSourceFactsTokens: args.config.recall.maxSourceFactsTokens,
-              }
-            : {}),
-          ...(args.config.recall.queryTimestamp
-            ? { queryTimestamp: args.config.recall.queryTimestamp }
-            : {}),
-          ...(scope.tagGroups?.length ? { tagGroups: scope.tagGroups } : {}),
-        }),
-      );
-      const results = filterRecallQuality(
-        textFromRecallResponse(response),
-        args.config.recall.minScores,
-      ).items;
-      blocks.push({
-        bankId: scope.bankId,
-        query,
-        results,
-        memoryCount: results.length,
-        rendered: "",
-      });
-    } catch (error) {
-      failures.push({
-        bankId: scope.bankId,
-        query,
-        error: redactError(error),
-        ...(scope.kind ? { kind: scope.kind } : {}),
-        ...(scope.tagGroups?.length ? { tagGroups: scope.tagGroups } : {}),
-      });
-    }
-  }
-  const recallRendered = renderRecallBlocks(blocks, args.config.recall.topK);
-  const cwd = args.cwd ?? process.cwd();
-  const identity = createMemoryIdentity(cwd, args.config);
-  const mental = await loadMentalModelsForScopes({
-    client: args.client,
-    config: args.config,
-    bankIds: args.scopes.map((scope) => scope.bankId),
-    bankKinds: args.scopes.map((scope) => (scope.kind === "global" ? "user" : "project")),
-    projectId: identity.projectId,
-  });
-  const rendered = [mental.rendered, recallRendered].filter(Boolean).join("\n\n");
-  return {
-    rendered,
-    blocks: blocks.map((block) => ({ ...block, rendered: recallRendered })),
-    failed: failures.length,
-    failures,
-  };
-}
-
-export type RecallQualityDropReason =
-  | "blank-memory"
-  | "recall-contamination"
-  | "duplicate-memory"
-  | "below-score-floor";
-
-export interface RecallQualityDecision {
-  item: RecallResultItem;
-  decision: "keep" | "drop";
-  reasons: RecallQualityDropReason[];
-}
-
-function normalizedMemoryText(item: RecallResultItem): string {
-  return itemText(item).replace(/\s+/g, " ").trim().toLowerCase();
-}
-
-function isRecallContamination(text: string): boolean {
-  return /<\/?hindsight[-_]memor(?:y|ies)>|<\/?hindsight-mental-models>|<\/?mental_models>|customType["']?\s*:\s*["']hindsight-(?:recall|mental-models)|last-recall\.json/.test(
-    text,
-  );
-}
-
-function isBelowScoreFloor(item: RecallResultItem, minScores?: RecallMinScores): boolean {
-  if (!minScores) return false;
-  const scores = item.scores;
-  // Fail open when Hindsight omits scores so BM25-only hits and passthrough rerankers
-  // are not silently discarded by local policy.
-  if (!scores) return false;
-  for (const field of RECALL_SCORE_FIELDS) {
-    const floor = minScores[field];
-    const value = scores[field];
-    if (typeof floor === "number" && typeof value === "number" && value < floor) return true;
-  }
-  return false;
-}
-
-export function classifyRecallQuality(
-  item: RecallResultItem,
-  seen: Set<string>,
-  minScores?: RecallMinScores,
-): RecallQualityDecision {
-  const text = normalizedMemoryText(item);
-  const reasons: RecallQualityDropReason[] = [];
-  if (!text) reasons.push("blank-memory");
-  if (isRecallContamination(itemText(item))) reasons.push("recall-contamination");
-  if (text && seen.has(text)) reasons.push("duplicate-memory");
-  if (isBelowScoreFloor(item, minScores)) reasons.push("below-score-floor");
-  if (!reasons.length) seen.add(text);
-  return { item, decision: reasons.length ? "drop" : "keep", reasons };
-}
-
-export function filterRecallQuality(
-  items: RecallResultItem[],
-  minScores?: RecallMinScores,
-): {
-  items: RecallResultItem[];
-  decisions: RecallQualityDecision[];
-  dropped: number;
-  reasonCounts: Partial<Record<RecallQualityDropReason, number>>;
-} {
-  const seen = new Set<string>();
-  const decisions = items.map((item) => classifyRecallQuality(item, seen, minScores));
-  const reasonCounts: Partial<Record<RecallQualityDropReason, number>> = {};
-  for (const decision of decisions) {
-    for (const reason of decision.reasons) reasonCounts[reason] = (reasonCounts[reason] ?? 0) + 1;
-  }
-  return {
-    items: decisions
-      .filter((decision) => decision.decision === "keep")
-      .map((decision) => decision.item),
-    decisions,
-    dropped: decisions.filter((decision) => decision.decision === "drop").length,
-    reasonCounts,
-  };
-}

package/node_modules/@luxusai/pi-hindsight/extensions/lifecycle/retain-cursor.ts

@@ -1,354 +0,0 @@
-import { createHash } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-
-export const RETAIN_CURSOR_VERSION = 3 as const;
-export const RETAIN_CURSOR_TAIL_WINDOW = 200;
-
-export interface SessionRetainCursor {
-  index: number;
-  chainHash: string;
-  idChainHash: string;
-  tailStart: number;
-  messageIds: string[];
-  fingerprints: string[];
-}
-
-export interface SessionRetainState {
-  cursor?: SessionRetainCursor;
-  legacyFingerprints?: Set<string>;
-}
-
-interface RetainCursorStoreV3 {
-  version: typeof RETAIN_CURSOR_VERSION;
-  sessions: Record<string, SessionRetainCursor | LegacySessionEntry>;
-}
-
-interface LegacySessionEntry {
-  legacyFingerprints: string[];
-}
-
-type RetainCursorStoreV1 = {
-  sessions: Record<string, string[]>;
-};
-
-interface SessionRetainCursorV2 {
-  index: number;
-  chainHash: string;
-  idChainHash: string;
-  messageIds: string[];
-  fingerprints: string[];
-}
-
-export function retainCursorPath(cwd: string): string {
-  return join(cwd, ".pi", "hindsight", "retain-cursors.json");
-}
-
-export function messageFingerprint(message: AgentMessage): string {
-  const m = message as unknown as Record<string, unknown>;
-  const stable = {
-    id: m.id,
-    role: m.role,
-    timestamp: m.timestamp,
-    content: m.content,
-    toolName: m.toolName,
-    isError: m.isError,
-    model: m.model,
-    stopReason: m.stopReason,
-  };
-  return createHash("sha256").update(JSON.stringify(stable)).digest("hex");
-}
-
-function messageId(message: AgentMessage): string {
-  const id = (message as unknown as Record<string, unknown>).id;
-  if (typeof id === "string") return id;
-  if (typeof id === "number") return String(id);
-  return "";
-}
-
-export function chainHash(fingerprints: readonly string[], throughIndex: number): string {
-  let hash = "";
-  for (let i = 0; i <= throughIndex; i++) {
-    const fingerprint = fingerprints[i];
-    if (fingerprint === undefined) break;
-    hash = createHash("sha256")
-      .update(hash + fingerprint)
-      .digest("hex");
-  }
-  return hash;
-}
-
-export function idChainHash(messages: readonly AgentMessage[], throughIndex: number): string {
-  let hash = "";
-  for (let i = 0; i <= throughIndex; i++) {
-    const message = messages[i];
-    if (!message) break;
-    hash = createHash("sha256")
-      .update(hash + messageId(message))
-      .digest("hex");
-  }
-  return hash;
-}
-
-function buildCursor(messages: readonly AgentMessage[], throughIndex: number): SessionRetainCursor {
-  const tailStart = Math.max(0, throughIndex - RETAIN_CURSOR_TAIL_WINDOW + 1);
-  const tailMessages = messages.slice(tailStart, throughIndex + 1);
-  const prefixFingerprints = messages.slice(0, throughIndex + 1).map(messageFingerprint);
-  return {
-    index: throughIndex,
-    chainHash: chainHash(prefixFingerprints, throughIndex),
-    idChainHash: idChainHash(messages, throughIndex),
-    tailStart,
-    messageIds: tailMessages.map(messageId),
-    fingerprints: tailMessages.map(messageFingerprint),
-  };
-}
-
-function migrateCursorToV3(cursor: SessionRetainCursorV2): SessionRetainCursor {
-  const tailStart = Math.max(0, cursor.index - RETAIN_CURSOR_TAIL_WINDOW + 1);
-  return {
-    index: cursor.index,
-    chainHash: cursor.chainHash,
-    idChainHash: cursor.idChainHash,
-    tailStart,
-    messageIds: cursor.messageIds.slice(tailStart),
-    fingerprints: cursor.fingerprints.slice(tailStart),
-  };
-}
-
-function isLegacySessionEntry(value: unknown): value is LegacySessionEntry {
-  return (
-    !!value &&
-    typeof value === "object" &&
-    !Array.isArray(value) &&
-    Array.isArray((value as LegacySessionEntry).legacyFingerprints)
-  );
-}
-
-function isSessionRetainCursorV2(value: unknown): value is SessionRetainCursorV2 {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const cursor = value as SessionRetainCursorV2;
-  return (
-    typeof cursor.index === "number" &&
-    typeof cursor.chainHash === "string" &&
-    typeof cursor.idChainHash === "string" &&
-    Array.isArray(cursor.messageIds) &&
-    Array.isArray(cursor.fingerprints) &&
-    !("tailStart" in cursor)
-  );
-}
-
-function isSessionRetainCursor(value: unknown): value is SessionRetainCursor {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const cursor = value as SessionRetainCursor;
-  return (
-    typeof cursor.index === "number" &&
-    typeof cursor.chainHash === "string" &&
-    typeof cursor.idChainHash === "string" &&
-    typeof cursor.tailStart === "number" &&
-    Array.isArray(cursor.messageIds) &&
-    Array.isArray(cursor.fingerprints)
-  );
-}
-
-function normalizeLegacyFingerprints(value: unknown): string[] {
-  if (!Array.isArray(value)) return [];
-  return value.filter((item): item is string => typeof item === "string");
-}
-
-function readLegacyStore(parsed: RetainCursorStoreV1): Record<string, LegacySessionEntry> {
-  const sessions: Record<string, LegacySessionEntry> = {};
-  for (const [key, value] of Object.entries(parsed.sessions ?? {})) {
-    const fingerprints = normalizeLegacyFingerprints(value);
-    if (fingerprints.length > 0) sessions[key] = { legacyFingerprints: fingerprints };
-  }
-  return sessions;
-}
-
-async function readRetainCursorStore(path: string): Promise<RetainCursorStoreV3> {
-  try {
-    const parsed = JSON.parse(await readFile(path, "utf8")) as unknown;
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-      return { version: RETAIN_CURSOR_VERSION, sessions: {} };
-    }
-
-    const version = (parsed as { version?: unknown }).version;
-    const sessions = (parsed as { sessions?: unknown }).sessions;
-    if (!sessions || typeof sessions !== "object" || Array.isArray(sessions)) {
-      return { version: RETAIN_CURSOR_VERSION, sessions: {} };
-    }
-
-    if (version === RETAIN_CURSOR_VERSION) {
-      const normalized: RetainCursorStoreV3["sessions"] = {};
-      for (const [key, value] of Object.entries(sessions)) {
-        if (isSessionRetainCursor(value)) normalized[key] = value;
-        else if (isLegacySessionEntry(value)) normalized[key] = value;
-      }
-      return { version: RETAIN_CURSOR_VERSION, sessions: normalized };
-    }
-
-    if (version === 2) {
-      const normalized: RetainCursorStoreV3["sessions"] = {};
-      for (const [key, value] of Object.entries(sessions)) {
-        if (isSessionRetainCursorV2(value)) normalized[key] = migrateCursorToV3(value);
-        else if (isLegacySessionEntry(value)) normalized[key] = value;
-      }
-      return { version: RETAIN_CURSOR_VERSION, sessions: normalized };
-    }
-
-    return {
-      version: RETAIN_CURSOR_VERSION,
-      sessions: readLegacyStore(parsed as RetainCursorStoreV1),
-    };
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      return { version: RETAIN_CURSOR_VERSION, sessions: {} };
-    }
-    throw error;
-  }
-}
-
-async function writeRetainCursorStore(path: string, store: RetainCursorStoreV3): Promise<void> {
-  await mkdir(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp`;
-  await writeFile(tmp, `${JSON.stringify(store, null, 2)}\n`, "utf8");
-  await rename(tmp, path);
-}
-
-export async function readSessionRetainState(
-  cwd: string,
-  sessionId: string,
-): Promise<SessionRetainState | undefined> {
-  const store = await readRetainCursorStore(retainCursorPath(cwd));
-  const entry = store.sessions[sessionId];
-  if (!entry) return undefined;
-  if (isLegacySessionEntry(entry)) {
-    return { legacyFingerprints: new Set(entry.legacyFingerprints) };
-  }
-  return { cursor: entry };
-}
-
-function legacyRetainStart(messages: readonly AgentMessage[], legacy: ReadonlySet<string>): number {
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const message = messages[i];
-    if (!message) continue;
-    if (legacy.has(messageFingerprint(message))) return i + 1;
-  }
-  return 0;
-}
-
-function prefixChainMatches(
-  messages: readonly AgentMessage[],
-  cursor: SessionRetainCursor,
-): boolean {
-  const fingerprints: string[] = [];
-  for (let i = 0; i <= cursor.index; i++) {
-    const message = messages[i];
-    if (!message) return false;
-    fingerprints.push(messageFingerprint(message));
-  }
-  return chainHash(fingerprints, cursor.index) === cursor.chainHash;
-}
-
-function filterWithCursor(
-  messages: readonly AgentMessage[],
-  cursor: SessionRetainCursor,
-): AgentMessage[] {
-  if (messages.length === 0) return [];
-
-  if (cursor.index < messages.length && prefixChainMatches(messages, cursor)) {
-    return messages.slice(cursor.index + 1);
-  }
-
-  const retained: AgentMessage[] = [];
-  let branched = false;
-
-  for (let i = 0; i < messages.length; i++) {
-    const message = messages[i];
-    if (!message) continue;
-
-    if (i > cursor.index) {
-      retained.push(message);
-      continue;
-    }
-
-    if (i < cursor.tailStart) {
-      if (branched) retained.push(message);
-      continue;
-    }
-
-    const offset = i - cursor.tailStart;
-    const idMatches = messageId(message) === cursor.messageIds[offset];
-    const fingerprintMatches = messageFingerprint(message) === cursor.fingerprints[offset];
-
-    if (!idMatches) {
-      branched = true;
-      retained.push(message);
-      continue;
-    }
-
-    if (branched) {
-      retained.push(message);
-      continue;
-    }
-
-    if (!fingerprintMatches) {
-      retained.push(message);
-    }
-  }
-
-  return retained;
-}
-
-export function filterNewRetainMessages(
-  messages: readonly AgentMessage[],
-  state: SessionRetainState | undefined,
-): AgentMessage[] {
-  if (!state) return [...messages];
-  if (state.cursor) return filterWithCursor(messages, state.cursor);
-  if (state.legacyFingerprints?.size) {
-    return messages.slice(legacyRetainStart(messages, state.legacyFingerprints));
-  }
-  return [...messages];
-}
-
-export async function advanceRetainCursor(
-  cwd: string,
-  sessionId: string,
-  allMessages: readonly AgentMessage[],
-  retainedThroughIndex: number,
-): Promise<void> {
-  if (retainedThroughIndex < 0 || retainedThroughIndex >= allMessages.length) return;
-
-  const path = retainCursorPath(cwd);
-  const store = await readRetainCursorStore(path);
-  const existing = store.sessions[sessionId];
-  const lastIndex = allMessages.length - 1;
-  let effectiveIndex = retainedThroughIndex;
-  if (isSessionRetainCursor(existing)) {
-    effectiveIndex = Math.max(existing.index, retainedThroughIndex);
-  }
-  effectiveIndex = Math.min(lastIndex, effectiveIndex);
-  store.sessions[sessionId] = buildCursor(allMessages, effectiveIndex);
-  await writeRetainCursorStore(path, store);
-}
-
-export function retainedThroughIndex(
-  allMessages: readonly AgentMessage[],
-  retainedMessages: readonly AgentMessage[],
-): number {
-  if (retainedMessages.length === 0) return -1;
-  const lastRetained = retainedMessages[retainedMessages.length - 1];
-  if (!lastRetained) return -1;
-  const lastId = messageId(lastRetained);
-  const lastFingerprint = messageFingerprint(lastRetained);
-  for (let i = 0; i < allMessages.length; i++) {
-    const message = allMessages[i];
-    if (!message) continue;
-    if (messageId(message) === lastId && messageFingerprint(message) === lastFingerprint) {
-      return i;
-    }
-  }
-  return -1;
-}