pi-fold 0.1.0 → 1.0.0

package/extensions/lib/advisory.ts

@@ -9,8 +9,15 @@ import type {
   ActiveContextSnapshot,
   ActiveContextState,
   AdvisoryMilestone,
+  GuidanceProfile,
+  SurfacingSuggestion,
+} from "./policy.ts";
+import {
+  contextBrand,
+  DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
+  DEFAULT_GUIDANCE_PROFILE,
+  GUIDANCE_PROFILES,
 } from "./policy.ts";
-import { contextBrand, DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN } from "./policy.ts";
 
 export { ADVISORY_BUDGETS };
 
@@ -35,18 +42,41 @@ export function clearArmedAdvisory(state: ActiveContextState): ActiveContextStat
   return { ...state, advisory };
 }
 
-export function advisorySchedule(
+export function normalizeGuidanceProfile(guidance: unknown = DEFAULT_GUIDANCE_PROFILE): GuidanceProfile {
+  if (!GUIDANCE_PROFILES.includes(guidance as GuidanceProfile)) {
+    throw new Error('guidance must be "pressure", "curation", or "minimal"');
+  }
+  return guidance as GuidanceProfile;
+}
+
+function guidanceRungs(
   snapshot: Pick<ActiveContextSnapshot, "policy" | "contextWindow">,
-): AdvisorySchedule {
-  const rungs = [
+  guidance: GuidanceProfile,
+): AdvisorySchedule["rungs"] {
+  const urgent = {
+    milestone: "urgent" as const,
+    threshold: hardFenceRatio(snapshot) - 0.03,
+    budget: ADVISORY_BUDGETS.urgent,
+  };
+  if (guidance === "minimal") return [urgent];
+  return [
+    ...(guidance === "curation"
+      ? [{ milestone: "orientation" as const, threshold: 0.25, budget: ADVISORY_BUDGETS.orientation }]
+      : []),
     { milestone: "notice" as const, threshold: 0.50, budget: ADVISORY_BUDGETS.notice },
     { milestone: "tools" as const, threshold: snapshot.policy.toolFoldRatio - 0.04,
       budget: ADVISORY_BUDGETS.tools },
     { milestone: "chapters" as const, threshold: snapshot.policy.prepareRatio - 0.05,
       budget: ADVISORY_BUDGETS.chapters },
-    { milestone: "urgent" as const, threshold: hardFenceRatio(snapshot) - 0.03,
-      budget: ADVISORY_BUDGETS.urgent },
+    urgent,
   ];
+}
+
+export function advisorySchedule(
+  snapshot: Pick<ActiveContextSnapshot, "policy" | "contextWindow">,
+  guidance: GuidanceProfile = DEFAULT_GUIDANCE_PROFILE,
+): AdvisorySchedule {
+  const rungs = guidanceRungs(snapshot, guidance);
   for (let index = rungs.length - 2; index >= 0; index -= 1) {
     rungs[index].threshold = Math.min(rungs[index].threshold, rungs[index + 1].threshold - 0.02);
   }
@@ -57,12 +87,36 @@ export function advisorySchedule(
   };
 }
 
+/**
+ * Record that an armed advisory actually REACHED the agent.
+ *
+ * The budget used to be spent when a milestone armed. Any automatic fold in the same
+ * context pass then cleared the arm before the projection was built, so a working
+ * ladder drained every milestone budget without ever emitting a word. Measured
+ * 2026-08-06 on an identical pressure schedule: an idle-ladder session delivered 7
+ * advisories, and a tool-using session delivered 0 while reporting notice, tools and
+ * chapters each "delivered" once. All four instrumented runs were the second case.
+ */
+export function recordAdvisoryDelivery(
+  state: ActiveContextState,
+  milestone: AdvisoryMilestone,
+): ActiveContextState {
+  const current = advisoryState(state);
+  const delivered = { ...current.delivered };
+  delivered[milestone] = (delivered[milestone] ?? 0) + 1;
+  const advisory = { ...current, delivered };
+  delete advisory.armed;
+  return { ...state, advisory };
+}
+
 export function updateAdvisoryMilestone(
   currentState: ActiveContextState,
   ratio: number,
   schedule: AdvisorySchedule,
   scheduleChanged: boolean,
   scheduleKey: string,
+  /** Spend the milestone budget on DELIVERY rather than on arming. */
+  countOnDelivery = false,
 ): { state: ActiveContextState; milestone: AdvisoryMilestone | null } {
   const current = advisoryState(currentState);
   if (scheduleChanged) {
@@ -78,12 +132,28 @@ export function updateAdvisoryMilestone(
       highWater = Math.min(highWater, index > 0 ? schedule.rungs[index - 1].threshold : 0);
     }
   }
-  const crossed = schedule.rungs.filter((rung) =>
-    highWater < rung.threshold && ratio >= rung.threshold &&
-    (current.delivered[rung.milestone] ?? 0) < rung.budget);
-  const selected = crossed.at(-1) ?? null;
+  let selected: AdvisorySchedule["rungs"][number] | null;
+  if (countOnDelivery) {
+    // Only ever the highest rung the current pressure has reached, so a plateau does
+    // not replay a descending cascade of stale milestones. A rung that has never been
+    // DELIVERED stays armable even after the high-water mark has passed it: the old
+    // ratchet locked out every rung that armed once and was cleared before it spoke.
+    const reached = schedule.rungs.filter((rung) => ratio >= rung.threshold).at(-1) ?? null;
+    const deliveries = reached ? current.delivered[reached.milestone] ?? 0 : 0;
+    selected = reached && deliveries < reached.budget &&
+      (highWater < reached.threshold || deliveries === 0)
+      ? reached
+      : null;
+  } else {
+    const crossed = schedule.rungs.filter((rung) =>
+      highWater < rung.threshold && ratio >= rung.threshold &&
+      (current.delivered[rung.milestone] ?? 0) < rung.budget);
+    selected = crossed.at(-1) ?? null;
+  }
   const delivered = { ...current.delivered };
-  if (selected) delivered[selected.milestone] = (delivered[selected.milestone] ?? 0) + 1;
+  if (selected && !countOnDelivery) {
+    delivered[selected.milestone] = (delivered[selected.milestone] ?? 0) + 1;
+  }
   const armed = selected
     ? { milestone: selected.milestone, threshold: selected.threshold, scheduleKey }
     : current.armed;
@@ -100,15 +170,52 @@ export function updateAdvisoryMilestone(
   };
 }
 
+/**
+ * Wording rule for every dosage below: report what is HAPPENING and name the actions
+ * that change it. The earlier phrasing asked the agent to fold proactively, which is
+ * advice it can only act on by interrupting its own task; the runtime folds either way,
+ * so the honest thing to say is what it will do and what reacting buys.
+ */
+function curationText(milestone: AdvisoryMilestone, percent: number, toolName: string): string {
+  if (milestone === "orientation") {
+    return "Collapsed folds are a browsable index of the work behind you, and their briefs sit in the cached " +
+      `prefix of the window, so paging that index costs almost nothing. Page it with ${toolName} ` +
+      `{"action":"status"} and expand what the current task needs with ${toolName} ` +
+      '{"action":"expand","id":"<fold-id>"}.';
+  }
+  if (milestone === "notice") {
+    return `Context is ${percent}% full, and the ladder is folding stale spans as it fills. Spans you fold ` +
+      `yourself carry your brief instead of a generated one: ${toolName} ` +
+      '{"action":"fold","marks":[{"ids":["<start>","<end>"],"brief":"<factual brief>"}]} batches several at ' +
+      `once, and ${toolName} {"action":"protect","ids":["<entry-id>"]} keeps what must stay raw out of every ` +
+      "fold. Continuing the task is the default; nothing here needs a reply.";
+  }
+  if (milestone === "tools") {
+    return "Completed read-only tool batches are what the ladder reclaims first, and their endpoint ids are in " +
+      "the live advisory. A batch it folds keeps a generated brief; one you fold keeps yours. Either way the " +
+      `exact entries come back with ${toolName} {"action":"expand","id":"<fold-id>"}, and a brief that does ` +
+      `not describe what you needed is corrected with ${toolName} ` +
+      '{"action":"rebrief","id":"<fold-id>","brief":"<factual brief>"}.';
+  }
+  return "Adjacent folds of finished work are the next thing the ladder consolidates. Handing two or more to " +
+    `${toolName} {"action":"fold","ids":["<fold-id>","<fold-id>"],"brief":"<factual brief>"} nests them under ` +
+    "a brief you wrote, leaving the oldest material deepest and still exactly recoverable; a boundary that " +
+    `came out wrong is re-cut with ${toolName} {"action":"reboundary","ids":["<start>","<end>"]}.`;
+}
+
 export function milestoneText(
   milestone: AdvisoryMilestone,
   sessionId: string,
   threshold: number,
   toolName: string,
   brandNoun = DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN,
+  guidance: GuidanceProfile = DEFAULT_GUIDANCE_PROFILE,
 ): string {
   const percent = Math.round(threshold * 100);
   const prefix = `[${contextBrand(brandNoun)} milestone ${milestone}; session ${sessionId.slice(0, 16)}]`;
+  if (guidance === "curation" && milestone !== "urgent") {
+    return `${prefix} ${curationText(milestone, percent, toolName)}`;
+  }
   if (milestone === "notice") {
     return `${prefix} Context pressure has crossed ${percent}%. Automatic folding is available. ` +
       `Inspect candidates exactly with ${toolName} {"action":"status"}.`;
@@ -119,13 +226,55 @@ export function milestoneText(
   }
   if (milestone === "chapters") {
     return `${prefix} The chapter preparation rung begins at ${percent}%. ` +
-      `Use eligibleChapter endpoints with ${toolName} ` +
-      '{"action":"fold","ids":["<start>","<end>"],"brief":"<factual brief>"}.';
+      `Closed chapters fold from the eligibleChapter endpoints in ${toolName} {"action":"status"}; ` +
+      `${toolName} {"action":"fold","ids":["<start>","<end>"],"brief":"<factual brief>"} folds one with ` +
+      "your own brief instead of a generated one.";
   }
   return `${prefix} The hard context fence is near. The next automatic action is a committed chapter fold ` +
     "or the provider request is aborted before transmission.";
 }
 
+/**
+ * The surfacing carrier. It rides the same ephemeral tail channel as the live
+ * advisory: appended after the stable prefix, never durable, never a mutation of
+ * the projection, and cleared whenever the next context event is built.
+ */
+export function surfacingText(input: {
+  suggestions: readonly SurfacingSuggestion[];
+  brandNoun?: string;
+}): string | null {
+  if (!input.suggestions.length) return null;
+  const brand = contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN);
+  const lines = input.suggestions.map((suggestion, index) => [
+    `${index + 1}. ${suggestion.id}${suggestion.depth ? ` (depth ${suggestion.depth})` : ""}: ${suggestion.text}`,
+    ...(suggestion.alternateRoute ? [`   peek (ephemeral read): ${suggestion.alternateRoute}`] : []),
+    `   expand (durable restore): ${suggestion.route}`,
+  ].join("\n"));
+  return boundReceiptText(
+    [
+      `[${brand} suggestions] ${input.suggestions.length} collapsed span(s) look relevant to the current ` +
+        "task. Peek reads one back ephemerally at any depth; expand restores it in place, outermost first. " +
+        "Ignoring them is a valid answer.",
+      ...lines,
+    ].join("\n"),
+    2_048,
+    `[${brand} suggestions] Relevant collapsed spans are unavailable this pass.`,
+  );
+}
+
+export interface AdvisoryCuration {
+  /** Room left before the truthful fence, in tokens. */
+  headroomTokens: number | null;
+  budgetTokens: number;
+  pendingMarks: number;
+  eligibleMarks: number;
+  /** What the pending marks would free, in TOKENS. A percentage is not actionable. */
+  freedTokens: number;
+  eligibleFreedTokens: number;
+  /** The share of what the request currently pays for that no pending decision reclaims. */
+  unmarkedShare: number;
+}
+
 export function liveAdvisoryText(input: {
   milestone: AdvisoryMilestone;
   ratio: number;
@@ -133,6 +282,7 @@ export function liveAdvisoryText(input: {
   chapterEndpoints: string[];
   remediationCount: number;
   brandNoun?: string;
+  curation?: AdvisoryCuration | null;
 }): string {
   const tools = input.toolEndpoints.length
     ? input.toolEndpoints.slice(0, 3).join(", ")
@@ -140,9 +290,16 @@ export function liveAdvisoryText(input: {
   const chapter = input.chapterEndpoints.length
     ? `${input.chapterEndpoints[0]}..${input.chapterEndpoints.at(-1)}`
     : "none";
+  const curation = input.curation
+    ? `headroom ${input.curation.headroomTokens ?? "unmeasured"} of ${input.curation.budgetTokens} tokens; ` +
+      `unmarked share ${Math.round(input.curation.unmarkedShare * 100)}%; ` +
+      `${input.curation.pendingMarks} pending mark(s), ${input.curation.eligibleMarks} eligible now, ` +
+      `together freeing about ${input.curation.eligibleFreedTokens} tokens of the ` +
+      `${input.curation.freedTokens} marked; `
+    : "";
   return boundReceiptText(
     `[${contextBrand(input.brandNoun ?? DEFAULT_ACTIVE_CONTEXT_BRAND_NOUN)} advisory] ` +
-      `pressure ${Math.round(input.ratio * 100)}%; milestone ${input.milestone}; ` +
+      `pressure ${Math.round(input.ratio * 100)}%; milestone ${input.milestone}; ${curation}` +
       `eligible read-only batch endpoints: ${tools}; eligibleChapter endpoints: ${chapter}; ` +
       `session milestone count: ${input.remediationCount}.`,
     2_048,

package/extensions/lib/canonical.ts

@@ -15,6 +15,26 @@ export function bytes(value: unknown): number {
   return Buffer.byteLength(typeof value === "string" ? value : stableStringify(value), "utf8");
 }
 
+export function boundedUtf8(text: string, maximumBytes: number): string {
+  const buffer = Buffer.from(text, "utf8");
+  if (buffer.length <= maximumBytes) return text;
+  // A multi-byte sequence cut by the bound decodes to one trailing replacement
+  // character; dropping it keeps the slice an exact prefix of the source.
+  return buffer.subarray(0, maximumBytes).toString("utf8").replace(/\uFFFD$/, "");
+}
+
+/**
+ * The suffix of `text` beginning at a byte offset. A multi-byte sequence cut by the
+ * offset decodes to one leading replacement character; dropping it keeps the slice an
+ * exact suffix of the source, which is what makes a paged peek losslessly rejoinable.
+ */
+export function utf8Slice(text: string, offsetBytes: number): string {
+  if (offsetBytes <= 0) return text;
+  const buffer = Buffer.from(text, "utf8");
+  if (offsetBytes >= buffer.length) return "";
+  return buffer.subarray(offsetBytes).toString("utf8").replace(/^�/, "");
+}
+
 export function ownValue(value: unknown, key: string): unknown {
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
   const descriptor = Object.getOwnPropertyDescriptor(value, key);