pi-fold 0.1.1 → 1.0.0

package/extensions/lib/tool-surface.ts

@@ -1,3 +1,12 @@
+/**
+ * Wording rule for everything in this file: describe units of WORK, never units of
+ * conversation. Text that presupposes turn-ending replies ("after the reply",
+ * "between tasks") tells a single-turn staged agent that a reply is the natural next
+ * move, and it rides in the tool surface of every request. It is the top unproven
+ * suspect for the iteration-2 phase flips, and saying the true thing instead costs
+ * nothing: the next model call that reads a result, a natural boundary in the work.
+ */
+
 type ToolHandler = (
   toolCallId: string,
   params: Record<string, unknown>,
@@ -14,17 +23,34 @@ export function buildActiveContextTool(input: {
   allowedActions: readonly string[];
   fullSurface: boolean;
   maxBriefChars: number;
+  statusDetails: readonly string[];
+  minPeekSliceBytes: number;
+  defaultPeekBytes: number;
   handler: ToolHandler;
 }) {
   const peekGuidance = input.allowedActions.includes("peek")
-    ? " Peek is the ephemeral point read: it returns one fold's exact source at any depth, ancestors still collapsed, and changes nothing, so the content arrives as a tool result that can later fold away as a completed read batch; 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 the raw source with the omitted middle stated -- at any depth, ancestors still collapsed, changing nothing. 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.`
+    : "";
+  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."
+    : "";
+  // Marking is yours, folding is the runtime's. The epoch guidance says how marks
+  // behave and stops there: there is no agent-callable commit verb to describe.
+  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."
     : "";
+  // The standing facts about how this runtime behaves. They belong HERE, in the tool
+  // surface, because the tool surface sits in the stable prefix: it is cached from the
+  // first request and costs nothing per request thereafter, forever. The same sentences
+  // delivered as in-window carriers cost a cache break on the pass that renders them
+  // and every pass that displaces them. Anything always true is said once, here.
+  const standingGuidance = " Folding is automatic, lossless and recoverable: the runtime folds stale spans on its own when the window needs room, nothing is ever discarded, and every folded span keeps its exact source. You are never asked to make room and no fold is ever announced in advance. Work normally and let it happen.";
   return {
     name: input.name,
     label: input.label,
     description: input.fullSurface
-      ? `Page, peek, fold, expand, refold, or protect exact Pi active-context evidence.${peekGuidance} 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 1200-character maximum.`
-      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance} 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 1200-character maximum.`,
+      ? `Page, peek, fold, expand, refold, protect, rebrief, or re-cut exact Pi active-context evidence.${peekGuidance}${correctionGuidance}${epochGuidance}${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 1200-character maximum.`
+      : `Use only the configured active-context actions: ${input.allowedActions.join(", ")}.${peekGuidance}${correctionGuidance}${epochGuidance}${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 1200-character maximum.`,
     parameters: {
       type: "object",
       additionalProperties: false,
@@ -33,6 +59,21 @@ 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 },
+            },
+          },
+        },
         brief: {
           type: "string",
           minLength: 1,
@@ -40,8 +81,13 @@ export function buildActiveContextTool(input: {
           description: "Factual fold brief; keep it at most 1000 characters to stay below the hard 1200-character limit.",
         },
         offset: { type: "integer", minimum: 0 },
+        bytes: {
+          type: "integer",
+          minimum: input.minPeekSliceBytes,
+          description: `Peek only: bytes of exact source to return, widening or narrowing the ${input.defaultPeekBytes}-byte default.`,
+        },
         limit: { type: "integer", minimum: 1, maximum: 100 },
-        detail: { type: "string", enum: ["fold_candidates", "tree"] },
+        detail: { type: "string", enum: [...input.statusDetails] },
       },
     },
     execute: input.handler,

package/extensions/lib/transcript.ts

@@ -3,6 +3,7 @@ import {
   evidenceRef,
   evidenceValue,
   isPlainRecord,
+  objectRefKey,
   sha256Text,
   stableStringify,
 } from "../json.ts";
@@ -20,6 +21,7 @@ import {
   DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX,
   DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
   DEFAULT_CONTEXT_WINDOW,
+  READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
   READ_ONLY_TOOLS_DEFAULT,
 } from "./policy.ts";
 import type {
@@ -69,15 +71,29 @@ export function leadingCompactionContinuation(messages: unknown[]): CompleteTurn
   return end > 1 && terminalAssistant(messages[end - 1]) ? { start: 1, end } : null;
 }
 
+/**
+ * The exact argument surface each read-only active-context action may carry. A call
+ * outside this surface is not classified read-only, so its batch never folds.
+ */
+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"]),
+});
+
 export function isReadOnlyContextTool(
   name: string,
   args?: unknown,
   toolName = DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
   readOnlyTools: ReadonlySet<string> = READ_ONLY_TOOLS_DEFAULT,
+  readOnlyContextActions: ReadonlySet<string> = READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
 ): boolean {
   if (readOnlyTools.has(name)) return true;
-  if (name !== toolName || !isPlainRecord(args) || ownValue(args, "action") !== "status") return false;
-  const allowed = new Set(["action", "offset", "limit"]);
+  if (name !== toolName || !isPlainRecord(args)) return false;
+  const action = ownValue(args, "action");
+  if (typeof action !== "string" || !readOnlyContextActions.has(action)) return false;
+  const permitted = ownValue(READ_ONLY_CONTEXT_ACTION_ARGUMENTS, action);
+  if (!Array.isArray(permitted)) return false;
+  const allowed = new Set(permitted as string[]);
   const keys = Reflect.ownKeys(args);
   for (let index = 0; index < keys.length; index += 1) {
     if (typeof keys[index] !== "string" || !allowed.has(keys[index] as string)) return false;
@@ -110,6 +126,7 @@ export function scanTurnToolBatches(
   allowIncomplete = false,
   toolName = DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
   readOnlyTools: ReadonlySet<string> = READ_ONLY_TOOLS_DEFAULT,
+  readOnlyContextActions: ReadonlySet<string> = READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
 ): ScannedToolBatches | null {
   if (!Number.isSafeInteger(turn.start) || !Number.isSafeInteger(turn.end) ||
       turn.start < 0 || turn.end > messages.length || turn.start >= turn.end) return null;
@@ -146,7 +163,9 @@ export function scanTurnToolBatches(
       const id = ownValue(part, "id");
       const name = ownValue(part, "name");
       if (typeof id !== "string" || !id || typeof name !== "string" || !name ||
-          calls.has(id) || !isReadOnlyContextTool(name, ownValue(part, "arguments"), toolName, readOnlyTools)) safe = false;
+          calls.has(id) || !isReadOnlyContextTool(
+            name, ownValue(part, "arguments"), toolName, readOnlyTools, readOnlyContextActions,
+          )) safe = false;
       else calls.set(id, { id, name, assistantIndex: index });
     }
     for (let resultIndex = index + 1; resultIndex < end; resultIndex += 1) {
@@ -194,8 +213,11 @@ export function validateTurnToolBatch(
   turn: CompleteTurn,
   toolName = DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
   readOnlyTools: ReadonlySet<string> = READ_ONLY_TOOLS_DEFAULT,
+  readOnlyContextActions: ReadonlySet<string> = READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
 ): ValidatedToolBatch | null {
-  const scanned = scanTurnToolBatches(messages, turn, false, toolName, readOnlyTools);
+  const scanned = scanTurnToolBatches(
+    messages, turn, false, toolName, readOnlyTools, readOnlyContextActions,
+  );
   return scanned && scanned.unsafeIndices.size === 0 ? { calls: scanned.calls } : null;
 }
 
@@ -380,6 +402,7 @@ export function mapActiveContext(input: {
   brandNoun?: string;
   entryTypePrefix?: string;
   readOnlyTools?: ReadonlySet<string>;
+  readOnlyContextActions?: ReadonlySet<string>;
   contextWindow?: number;
 }): ActiveContextSnapshot {
   const policy = Object.freeze({ ...ACTIVE_CONTEXT_POLICY, ...(input.policy ?? {}) }) as typeof ACTIVE_CONTEXT_POLICY;
@@ -473,7 +496,38 @@ export function mapActiveContext(input: {
     brandNoun: input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
     entryTypePrefix: input.entryTypePrefix ?? DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX,
     readOnlyTools: input.readOnlyTools ?? READ_ONLY_TOOLS_DEFAULT,
+    readOnlyContextActions: input.readOnlyContextActions ?? READ_ONLY_CONTEXT_ACTIONS_DEFAULT,
     contextWindow: reportedContextWindow ?? DEFAULT_CONTEXT_WINDOW,
     windowSource: reportedContextWindow === null ? "fallback" : "reported",
   };
 }
+
+/**
+ * The evidence boundary of the CURRENT turn: the position of the last terminal
+ * assistant message. Everything after it was gathered by the excursion still in
+ * progress, which is exactly the evidence a commit must not fold.
+ *
+ * Measured 2026-08-06 (rep 8): nineteen folds landed between the last read result and
+ * the agent's next reply, rewriting the projection from 938k to 487k chars, so the
+ * agent answered from a window where its own just-gathered evidence had become
+ * placeholders. Freshness in bytes did not catch it; the boundary is a TURN.
+ */
+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;
+}
+
+/** Every tool-result evidence key produced since that 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;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-fold",
-  "version": "0.1.1",
-  "description": "Lossless, agent-governed context folding for the Pi coding agent — only the oldest context changes; the fresh window stays untouched.",
+  "version": "1.0.0",
+  "description": "Lossless, agent-governed context folding for the Pi coding agent: only the oldest context changes; the fresh window stays untouched.",
   "keywords": [
     "pi-package",
     "pi",