pi-fold 2.0.0 → 3.0.0

package/extensions/lib/selection.ts

@@ -16,7 +16,6 @@ import {
   orderedRoots,
   refsInOrder,
   refsProtected,
-  toolRefsProtected,
   visibleCollapsedRoots,
 } from "./measurement.ts";
 import {
@@ -28,7 +27,6 @@ import {
 import {
   ACTIVE_CONTEXT_POLICY,
   DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
-  MAX_FOLD_SPAN_CHARS,
 } from "./policy.ts";
 import type {
   ActiveContextSnapshot,
@@ -42,7 +40,6 @@ import type {
 } from "./policy.ts";
 import {
   chapterSegments,
-  currentTurnBoundary,
   scanTurnToolBatches,
   structurallyClosedChapterUnits,
   terminalAssistant,
@@ -503,9 +500,7 @@ export function pinnedChildFold(
     const child = byId.get(part.foldId);
     if (!child) continue;
     const refs = flattenFoldRefs(child, state);
-    const pinned = child.kind === "tool-result"
-      ? toolRefsProtected(refs, state, snapshot)
-      : refsProtected(refs, state, snapshot);
+    const pinned = refsProtected(refs, state, snapshot);
     if (pinned) return child;
   }
   return null;
@@ -513,7 +508,7 @@ export function pinnedChildFold(
 
 export function pinnedNestingRefusal(pinned: ActiveFold, toolName: string): string {
   return `fold refused: ${pinned.id} is pinned, and nesting it would hide context you asked to keep. ` +
-    `Release it with ${toolName} {"action":"unprotect","ids":["${pinned.id}"]} first, ` +
+    `Release it with ${toolName} {"action":"unpin","ids":["${pinned.id}"]} first, ` +
     "or name a span that stops at its boundary.";
 }
 
@@ -676,7 +671,6 @@ function consolidationCandidate(
   if (refsProtected(raw, state, snapshot)) return null;
   if (raw.some((ref) => claims.refKeys.has(objectRefKey(ref)))) return null;
   const sourceRefs = candidateSourceRefs(parts, state);
-  if (sourceRefs.length > snapshot.policy.maxFoldSourceRefs) return null;
   return { kind: "consolidation", parts, sourceRefs };
 }
 
@@ -735,9 +729,8 @@ export function automaticToolBatches(
         refs.some((ref) => !ref || ref.role !== "toolResult")) continue;
     const exactRefs = refs as EvidenceRef[];
     const size = group.reduce((total, { item }) => total + bytes(item.message), 0);
-    if (exactRefs.length > snapshot.policy.maxFoldSourceRefs ||
-        toolRefsProtected(exactRefs, state, snapshot) || refsInOrder(snapshot, exactRefs) === null ||
-        size < snapshot.policy.minToolChars) continue;
+    if (refsProtected(exactRefs, state, snapshot) || refsInOrder(snapshot, exactRefs) === null ||
+        size < snapshot.thresholds.minFoldChars) continue;
     batches.push({ refs: exactRefs, indices: group.map(({ item }) => item.index), bytes: size });
   }
   return batches;
@@ -770,9 +763,7 @@ export function selectAutomaticRefold(
     if (claimedFoldIds.has(id)) return [];
     const fold = state.folds.find((item) => item.id === id);
     const interval = fold ? foldInterval(fold, state, snapshot) : null;
-    const protectedSource = fold && (fold.kind === "tool-result"
-      ? toolRefsProtected(flattenFoldRefs(fold, state), state, snapshot)
-      : refsProtected(flattenFoldRefs(fold, state), state, snapshot));
+    const protectedSource = fold && (refsProtected(flattenFoldRefs(fold, state), state, snapshot));
     return fold && interval && !protectedSource && !state.leases[id]
       ? [{ id, ...interval }]
       : [];
@@ -805,47 +796,9 @@ export function resolveFoldInputIds(
 export function chapterRangeIsUnitAligned(snapshot: ActiveContextSnapshot, start: number, end: number): boolean {
   const units = chapterUnits(snapshot).filter((unit) => unit.end > start && unit.start <= end);
   if (!units.length || units[0].start !== start || units.at(-1)!.end !== end + 1) return false;
-  if (new Set(units.map((unit) => unit.turnStart)).size > snapshot.policy.maxChapterTurns) return false;
   return units.every((unit, index) => index === 0 || unit.start === units[index - 1].end);
 }
 
-export function splitCandidateBySize(
-  snapshot: ActiveContextSnapshot,
-  state: ActiveContextState,
-  candidate: FoldCandidate,
-  maxChars: number = MAX_FOLD_SPAN_CHARS,
-): FoldCandidate[] {
-  if (candidate.kind !== "chapter") return [candidate];
-  const refs = candidate.sourceRefs.length ? candidate.sourceRefs : candidateSourceRefs(candidate.parts, state);
-  const indices = refs.map((ref) => exactMapped(snapshot, ref)?.index ?? -1);
-  if (!indices.length || indices.some((index) => index < 0)) return [candidate];
-  const start = Math.min(...indices);
-  const end = Math.max(...indices);
-  if (spanBytes(snapshot, start, end + 1) <= maxChars) return [candidate];
-  const units = chapterUnits(snapshot).filter((unit) => unit.start >= start && unit.end <= end + 1);
-  if (units.length < 2) return [candidate];
-  const split: FoldCandidate[] = [];
-  const emit = (from: number, to: number): boolean => {
-    const parts = partsForRange(snapshot, state, from, to, new Set<FoldKind>(["tool-result"]));
-    if (!parts) return false;
-    split.push({ kind: "chapter", parts, sourceRefs: candidateSourceRefs(parts, state) });
-    return true;
-  };
-  let runStart = units[0].start;
-  let runBytes = 0;
-  for (const unit of units) {
-    const size = spanBytes(snapshot, unit.start, unit.end);
-    if (runBytes > 0 && runBytes + size > maxChars) {
-      if (!emit(runStart, unit.start - 1)) return [candidate];
-      runStart = unit.start;
-      runBytes = 0;
-    }
-    runBytes += size;
-  }
-  if (runBytes > 0 && !emit(runStart, units.at(-1)!.end - 1)) return [candidate];
-  return split.length ? split : [candidate];
-}
-
 export function candidateSpanChars(
   snapshot: ActiveContextSnapshot,
   state: ActiveContextState,
@@ -986,11 +939,6 @@ export function snapSpanIds(
           `${absorb ? "end" : "near"} boundary`);
       }
     }
-    const boundary = currentTurnBoundary(snapshot);
-    if (boundary >= 0 && end > boundary) {
-      end = boundary;
-      note("span reached into the turn still in flight; corrected back to the last closed turn");
-    }
     const startUnit = units.find((unit) => start >= unit.start && start < unit.end);
     if (startUnit && startUnit.start !== start) {
       start = startUnit.start;
@@ -1001,23 +949,6 @@ export function snapSpanIds(
       end = endUnit.end - 1;
       note("span ended mid-unit; corrected to the end of its closed user/assistant/tool unit");
     }
-    const covered = units.filter((unit) => unit.start >= start && unit.end <= end + 1);
-    if (covered.length) {
-      const turns: number[] = [];
-      let clamped = end;
-      for (const unit of covered) {
-        if (!turns.includes(unit.turnStart)) {
-          if (turns.length >= snapshot.policy.maxChapterTurns) break;
-          turns.push(unit.turnStart);
-        }
-        clamped = unit.end - 1;
-      }
-      if (clamped < end) {
-        end = clamped;
-        note(`span covered more than the ${snapshot.policy.maxChapterTurns}-turn chapter limit; ` +
-          "corrected to the last turn that fits");
-      }
-    }
     if (start === passStart && end === passEnd) break;
   }
   if (!corrections.length || end < start ||
@@ -1067,14 +998,11 @@ export function manualFoldCandidate(
   options: { allowProtected?: boolean } = {},
 ): FoldCandidate {
   const blockedTool = (refs: EvidenceRef[]): boolean =>
-    !options.allowProtected && toolRefsProtected(refs, state, snapshot);
+    !options.allowProtected && refsProtected(refs, state, snapshot);
   const blocked = (refs: EvidenceRef[]): boolean =>
     !options.allowProtected && refsProtected(refs, state, snapshot);
   const owners = directFoldOwners(state.folds);
   const bounded = (candidate: FoldCandidate): FoldCandidate => {
-    if (candidate.sourceRefs.length > snapshot.policy.maxFoldSourceRefs) {
-      throw new Error(`Folds may include at most ${snapshot.policy.maxFoldSourceRefs} exact source references`);
-    }
     for (const part of candidate.parts) {
       if (part.kind !== "raw") continue;
       const ownerId = owners.get(objectRefKey(part.ref));

package/extensions/lib/tool-surface.ts

@@ -29,16 +29,16 @@ export function buildActiveContextTool(input: {
   handler: ToolHandler;
 }) {
   const peekGuidance = input.allowedActions.includes("peek")
-    ? ` Peek is the point read: it returns one fold's index view -- every nested fold's brief in full, plus the head and tail of that fold's own span with the omitted middle stated -- for any fold id, ancestors still collapsed, changing nothing. It serves ONE level: raw entries come back exactly, folds nested inside stay placeheld, and peeking a child id you see there returns that child's own bytes, so anything folded is one hop away at any depth. It returns at most ${input.defaultPeekBytes} bytes unless you widen it with bytes, and it stays in the window like any other tool result. Expand is the durable in-place restoration.`
+    ? ` Peek is the point read: it returns one fold's index view -- every nested fold's brief in full, plus the head and tail of that fold's own span with the omitted middle stated -- for any fold id, ancestors still collapsed, changing nothing. It serves ONE level: raw entries come back exactly, folds nested inside stay placeheld, and peeking a child id you see there returns that child's own bytes, so anything folded is one hop away at any depth. It returns at most ${input.defaultPeekBytes} bytes unless you widen it with bytes, and it is EPHEMERAL by default: the bytes ride only until your next message, your reply then the surviving trace, so extract what your current task needs from them in that reply. Peeking again is lossless and costs one append, so a read you turn out to need twice is cheap; pass ephemeral false when you need the bytes standing across several turns. Expand is the durable in-place restoration.`
     : "";
-  const correctionGuidance = input.allowedActions.includes("rebrief")
-    ? " Curation is correctable: rebrief replaces a fold's brief, and reboundary with ids re-cuts a span into exactly one fold, which merges adjacent folds when the span covers several and splits one when the span sits inside it. Reboundary with a single id returns that fold's span to raw."
+  const correctionGuidance = input.allowedActions.includes("reboundary")
+    ? " Curation is correctable: reboundary with ids re-cuts a span into exactly one fold, which merges adjacent folds when the span covers several and splits one when the span sits inside it. Reboundary with a single id returns that fold's span to raw. A brief is written when you mark the span; a standing fold's brief is not rewritten, because rewriting it rewrites the projection at that fold's placeholder and costs the whole prefix cache from there on."
     : "";
-  const pinGuidance = input.allowedActions.includes("protect")
-    ? " Protect is the pin: protect with ids holds folds or entries against automatic folding, consolidation and refolding until unprotect releases them, so an expanded span you still need stays expanded. Protect reveals nothing on its own: a folded span stays folded, just held. Pinning moves no context bytes, and fold receipts report how much mass you have pinned."
+  const pinGuidance = input.allowedActions.includes("pin")
+    ? " Pin with ids holds folds or entries against automatic folding, consolidation and refolding until unpin releases them, so an expanded span you still need stays expanded. Pin reveals nothing on its own: a folded span stays folded, just held. Pinning moves no context bytes, and fold receipts report how much mass you have pinned."
     : "";
-  const epochGuidance = input.allowedActions.includes("unmark")
-    ? " Fold scheduling is epoch mode: fold records pending marks and moves no context bytes, and the runtime applies every pending mark in one rewrite when the fold event fires. Mark SEVERAL spans in one call: marks carries several {ids, brief} pairs, and one call answers with your whole picture, every span now held plus the unmarked remainder and what share of the non-fresh window it is. Between fold events nothing else in your context changes, so that result is where the picture lives. Mark freely as you work; when to fold is the runtime's to decide, and unmark withdraws a mark you no longer want."
+  const epochGuidance = input.allowedActions.includes("brief")
+    ? " THE RUNTIME CUTS THE FOLDS AND YOU ANNOTATE THEM. As raw material piles up it is cut into pending folds behind you, stalest first. A pending fold moves NO context bytes: you keep seeing the raw material exactly as it is, and the fold reaches your window only when a commit applies it. You are told when folds are cut and which ones carry no brief yet. Answer with brief, one id and one sentence: you know why the span mattered and what you will want back from it, and the deterministic brief that fills the gap reads the span alone and does not. Writing a brief on a pending fold is FREE, because the fold is not in your window yet; briefing a standing fold is refused, because its placeholder is in your window and rewriting it rewrites your context from that point on. reboundary re-cuts a span the runtime got wrong, unmark withdraws a cut you do not want taken, and when to commit stays the runtime's to decide."
     : "";
   const recoveryGuidance = input.allowedActions.includes("expand")
     ? " A fold brief is an index entry, not the source: when a question or task depends on material that is folded, peek or expand that fold and answer from the exact bytes, never from memory of them. Recalling folded detail without reopening it is how specifics get misremembered."
@@ -48,8 +48,8 @@ export function buildActiveContextTool(input: {
     name: input.name,
     label: input.label,
     description: input.fullSurface
-      ? `Page, peek, fold, expand, refold, protect, rebrief, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Mutations persist immediately and affect the next model call inside the same continuing turn; no turn boundary is required. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`
-      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Call fold only by copying the exact eligibleChapter.action returned by status; if status has no eligibleChapter, continue the task without folding. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`,
+      ? `Page, peek, brief, expand, refold, pin, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Mutations persist immediately and affect the next model call inside the same continuing turn; no turn boundary is required. Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`
+      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${pinGuidance}${epochGuidance}${recoveryGuidance}${standingGuidance} Supplied fold briefs have a hard ${input.maxBriefChars}-character maximum.`,
     parameters: {
       type: "object",
       additionalProperties: false,
@@ -58,35 +58,24 @@ export function buildActiveContextTool(input: {
         action: { type: "string", enum: input.allowedActions },
         ids: { type: "array", minItems: 1, maxItems: 64, items: { type: "string", minLength: 1 } },
         id: { type: "string", minLength: 1 },
-        marks: {
-          type: "array",
-          minItems: 1,
-          maxItems: 64,
-          description: "Fold only: several spans with their own briefs in one call, which is the shape to prefer. An invalid or overlapping span is corrected to the nearest valid edge and the correction is reported back.",
-          items: {
-            type: "object",
-            additionalProperties: false,
-            required: ["ids"],
-            properties: {
-              ids: { type: "array", minItems: 1, maxItems: 64, items: { type: "string", minLength: 1 } },
-              brief: {
-                type: "string",
-                minLength: 1,
-                maxLength: input.maxBriefChars,
-                description: "Write one for every span you mark. You know why the span mattered and " +
-                  "what you will want back from it; the deterministic brief that fills the gap " +
-                  "reads the span alone and does not.",
-              },
-            },
-          },
-        },
         brief: {
           type: "string",
           minLength: 1,
           maxLength: input.maxBriefChars,
-          description: `Factual fold brief, at most ${input.maxBriefChars} characters.`,
+          description: "Brief only: what this pending fold covers and what you will want " +
+            `back from it, at most ${input.maxBriefChars} characters. Free to write, ` +
+            "because the fold it names is not in your window yet.",
         },
         offset: { type: "integer", minimum: 0 },
+        ephemeral: {
+          type: "boolean",
+          description: "Peek only. Default TRUE: the returned bytes ride your context " +
+            "exactly until your next message, then their place holds a one-line " +
+            "placeholder and your reply is the surviving trace, so extract what you need " +
+            "into that reply. Peeking again is lossless. Pass false to keep the result " +
+            "standing like any other tool result, which is what you want when the bytes " +
+            "have to survive several turns of work.",
+        },
         bytes: {
           type: "integer",
           minimum: input.minPeekSliceBytes,
@@ -103,8 +92,10 @@ export function buildActiveContextTool(input: {
 export function buildActiveContextCommands(input: {
   statusName: string;
   foldName: string;
+  editorName: string;
   statusHandler: CommandHandler;
   foldHandler: CommandHandler;
+  editorHandler: CommandHandler;
 }) {
   return [
     {
@@ -114,9 +105,14 @@ export function buildActiveContextCommands(input: {
     },
     {
       name: input.foldName,
-      description: "Losslessly fold a stale context span, or \"commit\" to apply every eligible mark now; " +
+      description: "Commit every staged fold in one epoch; with explicit ids, folds exactly that span now; " +
         "works without a main-model request",
       handler: input.foldHandler,
     },
+    {
+      name: input.editorName,
+      description: "Open the context window editor: occupancy, fold roots and briefs, staged marks, pins",
+      handler: input.editorHandler,
+    },
   ];
 }

package/extensions/lib/transcript.ts

@@ -3,12 +3,10 @@ import {
   evidenceRef,
   evidenceValue,
   isPlainRecord,
-  objectRefKey,
   sha256Text,
   stableStringify,
 } from "../json.ts";
 import {
-  bytes,
   clone,
   messageRole,
   ownValue,
@@ -24,7 +22,6 @@ import {
   DEFAULT_THRESHOLDS,
   PEEK_READ_ONLY_CONTEXT_ACTIONS,
   servingBudgetTokens,
-  zoneBytes,
 } from "./policy.ts";
 import type {
   ActiveContextSnapshot,
@@ -70,7 +67,13 @@ export function leadingCompactionContinuation(messages: unknown[]): CompleteTurn
 
 export const READ_ONLY_CONTEXT_ACTION_ARGUMENTS: Readonly<Record<string, readonly string[]>> = Object.freeze({
   status: Object.freeze(["action", "detail", "offset", "limit"]),
-  peek: Object.freeze(["action", "id"]),
+  // offset and bytes are the tool surface's own narrowing parameters: a paged or
+  // narrowed peek is as byte-inert as a bare one, and excluding them made the
+  // read built to SAVE window mass linger as raw mass past the reclaimer.
+  // ephemeral joins them for the same reason: it changes when the RESULT leaves
+  // the projection, never what the call moves, and a call the reclaimer cannot
+  // claim would linger as exactly the mass the parameter exists to shed.
+  peek: Object.freeze(["action", "id", "offset", "bytes", "ephemeral"]),
 });
 
 export function isAutoFoldableToolCall(
@@ -317,7 +320,14 @@ export function unsafeChapterIndices(messages: unknown[]): Set<number> {
   return unsafe;
 }
 
-export function freshBoundary(messages: unknown[], turns: CompleteTurn[], freshBytes: number): number {
+/**
+ * The first index of an unfinished user turn, or the end of the transcript when the last
+ * turn completed. Folding into an unfinished turn leaves a user message whose tool calls are
+ * unanswered, which is malformed for every provider, so this is a validity boundary rather
+ * than a curation preference. The fresh-tail byte walk that used to sit here is deleted:
+ * nothing decided on it, and stale-first ordering already leaves recent material last.
+ */
+export function freshBoundary(messages: unknown[], turns: CompleteTurn[]): number {
   if (!messages.length) return 0;
   let unfinishedUser = messages.length;
   for (let index = messages.length - 1; index >= 0; index -= 1) {
@@ -329,36 +339,7 @@ export function freshBoundary(messages: unknown[], turns: CompleteTurn[], freshB
     unfinishedUser = complete ? messages.length : index;
     break;
   }
-  const leading = leadingCompactionContinuation(messages);
-  let boundary = Math.min(messages.length, unfinishedUser);
-  while (boundary > 0) {
-    const suffix: unknown[] = [];
-    for (let index = boundary; index < messages.length; index += 1) suffix.push(messages[index]);
-    if (bytes(suffix) >= freshBytes) break;
-    let previous: CompleteTurn | null = null;
-    for (let turnIndex = 0; turnIndex < turns.length; turnIndex += 1) {
-      if (turns[turnIndex].start < boundary) previous = turns[turnIndex];
-    }
-    if (!previous) { boundary = leading?.end ?? 0; break; }
-    boundary = previous.start;
-  }
-  return boundary;
-}
-
-export function toolFreshIndices(
-  messages: unknown[],
-  _turns: CompleteTurn[],
-  freshBytes: number,
-): Set<number> {
-  const protectedIndices = new Set<number>();
-  let tailBytes = 0;
-  let boundary = messages.length;
-  while (boundary > 0 && tailBytes < freshBytes) {
-    boundary -= 1;
-    tailBytes += bytes(messages[boundary]);
-  }
-  for (let index = boundary; index < messages.length; index += 1) protectedIndices.add(index);
-  return protectedIndices;
+  return Math.min(messages.length, unfinishedUser);
 }
 
 type EntryEvidence = { message: unknown; ref: BranchObject["ref"] };
@@ -486,17 +467,13 @@ export function mapActiveContext(input: {
   const budgetTokens = input.netBudget === true
     ? (reportedContextWindow ?? DEFAULT_CONTEXT_WINDOW)
     : servingBudgetTokens(reportedContextWindow ?? DEFAULT_CONTEXT_WINDOW);
-  const freshBytes = zoneBytes(thresholds.freshTail, budgetTokens);
   const turns = completeTurns(input.eventMessages);
-  const boundary = freshBoundary(input.eventMessages, turns, freshBytes);
+  const boundary = freshBoundary(input.eventMessages, turns);
   const protectedIndices = unsafeChapterIndices(input.eventMessages);
-  const toolProtectedIndices = toolFreshIndices(input.eventMessages, turns, freshBytes);
-  for (const index of toolProtectedIndices) protectedIndices.add(index);
   for (let mappedIndex = 0; mappedIndex < mapped.length; mappedIndex += 1) {
     const item = mapped[mappedIndex];
     if (item.ref) continue;
     protectedIndices.add(item.index);
-    toolProtectedIndices.add(item.index);
   }
   const snapshot: ActiveContextSnapshot = {
     sessionId: input.sessionId,
@@ -508,7 +485,6 @@ export function mapActiveContext(input: {
     thresholds,
     budgetTokens,
     protectedIndices,
-    toolProtectedIndices,
     policy,
     toolName: input.toolName ?? DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
     brandNoun: input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
@@ -520,22 +496,3 @@ export function mapActiveContext(input: {
   };
   return snapshot;
 }
-
-export function currentTurnBoundary(snapshot: Pick<ActiveContextSnapshot, "messages">): number {
-  let boundary = -1;
-  for (let index = 0; index < snapshot.messages.length; index += 1) {
-    if (terminalAssistant(snapshot.messages[index])) boundary = index;
-  }
-  return boundary;
-}
-
-export function currentTurnRefKeys(snapshot: ActiveContextSnapshot): Set<string> {
-  const boundary = currentTurnBoundary(snapshot);
-  const keys = new Set<string>();
-  for (const item of snapshot.mapped) {
-    if (item.index <= boundary || !item.ref) continue;
-    if (messageRole(item.message) !== "toolResult") continue;
-    keys.add(objectRefKey(item.ref));
-  }
-  return keys;
-}