pi-fold 0.1.0 → 0.1.1

package/extensions/lib/folding.ts

@@ -9,6 +9,7 @@ import {
   stableStringify,
 } from "../json.ts";
 import {
+  boundedUtf8,
   bytes,
   clone,
   messageRole,
@@ -41,6 +42,7 @@ import {
   validateFoldForest,
 } from "./persistence.ts";
 import {
+  ACTIVE_CONTEXT_POLICY,
   activeContextBrand,
   activeContextSource,
   CONSOLIDATION_WIDTH_THRESHOLD,
@@ -849,14 +851,8 @@ export function foldStatusRow(fold: ActiveFold, state: ActiveContextState, snaps
   };
 }
 
-export function activeContextStatus(
-  snapshot: ActiveContextSnapshot,
-  state: ActiveContextState,
-  offset = 0,
-  limit = 40,
-  maximumChapterSourceRefs = Number.MAX_SAFE_INTEGER,
-): Record<string, unknown> {
-  const roots = orderedRoots(state, snapshot).map((item) => item.fold.id);
+/** Every fold, nested ones included, in transcript order with each parent before its children. */
+export function orderedFoldTree(state: ActiveContextState, snapshot: ActiveContextSnapshot): ActiveFold[] {
   const byId = foldMap(state);
   const ordered: ActiveFold[] = [];
   const seen = new Set<string>();
@@ -867,7 +863,42 @@ export function activeContextStatus(
     ordered.push(fold);
     for (const child of childFoldIds(fold)) visit(child);
   };
-  for (const root of roots) visit(root);
+  for (const root of orderedRoots(state, snapshot)) visit(root.fold.id);
+  return ordered;
+}
+
+export function foldDepth(state: ActiveContextState, fold: ActiveFold): number {
+  const byId = foldMap(state);
+  let depth = 0;
+  for (let parentId = fold.parentId; parentId; parentId = byId.get(parentId)?.parentId ?? null) depth += 1;
+  return depth;
+}
+
+export function foldTreeDetail(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+): Array<Record<string, unknown>> {
+  return orderedFoldTree(state, snapshot).map((fold) => ({
+    id: fold.id,
+    kind: fold.kind,
+    depth: foldDepth(state, fold),
+    parentId: fold.parentId,
+    brief: fold.brief,
+    sourceCount: flattenFoldRefs(fold, state).length,
+    state: state.expanded.includes(fold.id) ? "expanded" : "folded",
+    peekable: true,
+  }));
+}
+
+export function activeContextStatus(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  offset = 0,
+  limit = 40,
+  maximumChapterSourceRefs = Number.MAX_SAFE_INTEGER,
+): Record<string, unknown> {
+  const roots = orderedRoots(state, snapshot).map((item) => item.fold.id);
+  const ordered = orderedFoldTree(state, snapshot);
   const selected = ordered.slice(offset, offset + limit);
   const protectedKeys = explicitProtectedKeys(state);
   const objects = snapshot.mapped.flatMap((item) => item.ref ? [{
@@ -1010,3 +1041,51 @@ export function recoverFoldMessages(input: {
     return clone(message);
   });
 }
+
+/**
+ * Ephemeral point read of one fold's exact source at any depth. It recovers the same
+ * SHA-256-verified messages expansion restores, bounded for the reply, and changes no
+ * projection: the fold stays collapsed and the durable state is untouched.
+ */
+export function peekFoldSource(input: {
+  foldId: string;
+  state: ActiveContextState;
+  entries: Array<Record<string, unknown>>;
+  sessionId: string;
+  maximumBytes?: number;
+  projectEntry?: (entry: Record<string, unknown>) => unknown[];
+}): Record<string, unknown> {
+  const fold = input.state.folds.find((item) => item.id === input.foldId);
+  if (!fold) throw new Error(`Unknown active-context fold ${input.foldId}`);
+  const messages = recoverFoldMessages({
+    foldId: input.foldId,
+    state: input.state,
+    entries: input.entries,
+    sessionId: input.sessionId,
+    projectEntry: input.projectEntry,
+  });
+  const source = stableStringify(messages);
+  const sourceBytes = bytes(source);
+  const returned = boundedUtf8(source, input.maximumBytes ?? ACTIVE_CONTEXT_POLICY.maxChapterChars);
+  const returnedBytes = bytes(returned);
+  const truncated = returnedBytes < sourceBytes;
+  return {
+    version: 1,
+    action: "peek",
+    id: fold.id,
+    kind: fold.kind,
+    parentId: fold.parentId,
+    depth: foldDepth(input.state, fold),
+    brief: fold.brief,
+    sourceCount: messages.length,
+    sourceSha256: fold.sourceSha256,
+    sourceBytes,
+    returnedBytes,
+    truncated,
+    note: truncated
+      ? `Truncated: this reply carries the first ${returnedBytes} of ${sourceBytes} exact source bytes; ` +
+        `expand ${fold.id} to restore the complete source in place.`
+      : "Complete exact source; the fold stayed collapsed and no projection changed.",
+    source: returned,
+  };
+}

package/extensions/lib/persistence.ts

@@ -22,6 +22,7 @@ import {
   EXPAND_LEASE_GENERATIONS,
   MAX_ADVISORY_DELIVERIES_PER_MILESTONE,
   MAX_EXPAND_LEASES,
+  SURFACING_MAX_LOG_RECORDS,
 } from "./policy.ts";
 import type {
   ActiveContextCheckpointV2,
@@ -36,6 +37,7 @@ import type {
   FoldRecordEntry,
   FoldRecordRef,
   PreparedFold,
+  SurfacingRecord,
 } from "./policy.ts";
 
 export const ACTIVE_FOLD_KEYS = [
@@ -49,6 +51,8 @@ export const PREPARED_FOLD_KEYS = [
 export const ACTIVE_STATE_KEYS = ["version", "sessionId", "revision", "folds", "expanded", "protected"] as const;
 export const FOLD_RECORD_REF_KEYS = ["id", "sha256"] as const;
 export const FOLD_RECORD_ENTRY_KEYS = ["version", "sessionId", "foldId", "recordSha256", "fold"] as const;
+export const SURFACING_RECORD_KEYS = ["source", "id", "score", "ordinal", "outcome"] as const;
+export const SURFACING_OUTCOMES = Object.freeze(["shown", "accept", "reject"] as const);
 export const STATE_CHECKPOINT_V2_KEYS = [
   "version", "kind", "sessionId", "revision", "foldRefs", "expanded", "protected", "prepared", "stateSha256",
 ] as const;
@@ -67,6 +71,24 @@ export function validTokensSinceToolFold(value: unknown): value is number {
   return Number.isSafeInteger(value) && Number(value) >= 0;
 }
 
+export function validSurfacingRecord(value: unknown): value is SurfacingRecord {
+  if (!exactRecord(value, SURFACING_RECORD_KEYS)) return false;
+  const score = ownValue(value, "score");
+  return typeof ownValue(value, "source") === "string" && Boolean(ownValue(value, "source")) &&
+    typeof ownValue(value, "id") === "string" && Boolean(ownValue(value, "id")) &&
+    typeof score === "number" && Number.isFinite(score) && Number(score) >= 0 && Number(score) <= 1 &&
+    Number.isSafeInteger(ownValue(value, "ordinal")) && Number(ownValue(value, "ordinal")) >= 0 &&
+    SURFACING_OUTCOMES.includes(ownValue(value, "outcome") as SurfacingRecord["outcome"]);
+}
+
+export function parseSurfacingLog(value: unknown): SurfacingRecord[] {
+  const records = denseOwnArrayValues(value);
+  if (!records || records.length > SURFACING_MAX_LOG_RECORDS || !records.every(validSurfacingRecord)) {
+    throw new Error("Invalid active-context surfacing log");
+  }
+  return clone(records) as SurfacingRecord[];
+}
+
 export function parseLeases(value: unknown, foldIds?: ReadonlySet<string>): Record<string, number> {
   if (!isPlainRecord(value)) throw new Error("Invalid active-context expand leases");
   const entries = Object.entries(value);
@@ -235,11 +257,13 @@ export function parseActiveContextState(
   const hasTokensSinceToolFold = recordLike &&
     Object.prototype.hasOwnProperty.call(value, "tokensSinceToolFold");
   const hasLeases = recordLike && Object.prototype.hasOwnProperty.call(value, "leases");
+  const hasSurfacing = recordLike && Object.prototype.hasOwnProperty.call(value, "surfacing");
   const extraKeys = [
     ...(hasPrepared ? ["prepared"] : []),
     ...(hasAdvisory ? ["advisory"] : []),
     ...(hasTokensSinceToolFold ? ["tokensSinceToolFold"] : []),
     ...(hasLeases ? ["leases"] : []),
+    ...(hasSurfacing ? ["surfacing"] : []),
   ];
   if (!exactRecord(value, [...ACTIVE_STATE_KEYS, ...extraKeys])) throw new Error("Invalid active-context state keys");
   const folds = denseOwnArrayValues(ownValue(value, "folds"));
@@ -265,8 +289,9 @@ export function parseActiveContextState(
     throw new Error("Invalid active-context tool-fold cadence");
   }
   const leases = hasLeases ? parseLeases(ownValue(value, "leases"), ids) : {};
+  const surfacing = hasSurfacing ? parseSurfacingLog(ownValue(value, "surfacing")) : [];
   const source = clone(value) as unknown as ActiveContextState;
-  // Provenance normalization is presentation-only — never mutate a durable
+  // Provenance normalization is presentation-only; never mutate a durable
   // content-addressed fold record: changing its bytes causes the next re-persist
   // to report a conflicting durable fold and suspend automatic management.
   return {
@@ -280,6 +305,9 @@ export function parseActiveContextState(
       ? Number(ownValue(value, "tokensSinceToolFold"))
       : 0,
     leases,
+    // Omitted when empty so every state written before surfacing existed keeps its
+    // exact digest; the replay digest is order- and presence-sensitive by design.
+    ...(surfacing.length ? { surfacing } : {}),
     ...(hasAdvisory
       ? { advisory: clone(source.advisory!) }
       : defaultAdvisory ? { advisory: { highWater: 0, delivered: {} } } : {}),
@@ -355,6 +383,7 @@ export function sameStateProjection(left: ActiveContextState, right: ActiveConte
     const normalizedState = { ...clone(value), revision: 0 } as Partial<ActiveContextState>;
     if (normalizedState.tokensSinceToolFold === 0) delete normalizedState.tokensSinceToolFold;
     if (normalizedState.leases && Object.keys(normalizedState.leases).length === 0) delete normalizedState.leases;
+    if (normalizedState.surfacing && normalizedState.surfacing.length === 0) delete normalizedState.surfacing;
     return normalizedState;
   };
   return stableStringify(normalized(left)) === stableStringify(normalized(right));
@@ -395,6 +424,7 @@ export function validateV2ProjectionFields(
   advisoryValue: unknown,
   tokensSinceToolFoldValue: unknown,
   leasesValue: unknown,
+  surfacingValue?: unknown,
 ): {
   expanded: string[];
   protected: EvidenceRef[];
@@ -402,6 +432,7 @@ export function validateV2ProjectionFields(
   advisory?: NonNullable<ActiveContextState["advisory"]>;
   tokensSinceToolFold: number;
   leases: Record<string, number>;
+  surfacing: SurfacingRecord[];
 } {
   const expanded = denseOwnArrayValues(expandedValue);
   const protectedRefs = denseOwnArrayValues(protectedValue);
@@ -419,6 +450,7 @@ export function validateV2ProjectionFields(
     throw new Error("Invalid active-context v2 tool-fold cadence");
   }
   const leases = leasesValue === undefined ? {} : parseLeases(leasesValue);
+  const surfacing = surfacingValue === undefined ? [] : parseSurfacingLog(surfacingValue);
   return {
     expanded: clone(expanded) as string[],
     protected: clone(protectedRefs) as EvidenceRef[],
@@ -428,6 +460,7 @@ export function validateV2ProjectionFields(
     }),
     tokensSinceToolFold: tokensSinceToolFoldValue === undefined ? 0 : Number(tokensSinceToolFoldValue),
     leases,
+    surfacing,
   };
 }
 
@@ -439,10 +472,13 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
     Object.prototype.hasOwnProperty.call(value, "tokensSinceToolFold"));
   const hasLeases = Boolean(value && typeof value === "object" &&
     Object.prototype.hasOwnProperty.call(value, "leases"));
+  const hasSurfacing = Boolean(value && typeof value === "object" &&
+    Object.prototype.hasOwnProperty.call(value, "surfacing"));
   const optionalKeys = [
     ...(hasAdvisory ? ["advisory"] : []),
     ...(hasTokensSinceToolFold ? ["tokensSinceToolFold"] : []),
     ...(hasLeases ? ["leases"] : []),
+    ...(hasSurfacing ? ["surfacing"] : []),
   ];
   const checkpoint = kind === "checkpoint" &&
     exactRecord(value, [...STATE_CHECKPOINT_V2_KEYS, ...optionalKeys]);
@@ -457,6 +493,7 @@ export function parseActiveContextStateV2(value: unknown, sessionId: string): Ac
   validateV2ProjectionFields(
     ownValue(value, "expanded"), ownValue(value, "protected"), ownValue(value, "prepared"),
     ownValue(value, "advisory"), ownValue(value, "tokensSinceToolFold"), ownValue(value, "leases"),
+    ownValue(value, "surfacing"),
   );
   if (checkpoint) {
     const refs = denseOwnArrayValues(ownValue(value, "foldRefs"));
@@ -521,7 +558,7 @@ export function stateFromFoldRefs(
   wire: Pick<
     ActiveContextCheckpointV2,
     "sessionId" | "revision" | "expanded" | "protected" | "prepared" | "advisory" |
-      "tokensSinceToolFold" | "leases"
+      "tokensSinceToolFold" | "leases" | "surfacing"
   >,
   refs: FoldRecordRef[],
   records: Map<string, FoldRecordEntry>,
@@ -541,6 +578,7 @@ export function stateFromFoldRefs(
     protected: clone(wire.protected),
     tokensSinceToolFold: wire.tokensSinceToolFold ?? 0,
     leases: clone(wire.leases ?? {}),
+    ...(wire.surfacing?.length ? { surfacing: clone(wire.surfacing) } : {}),
     ...(wire.advisory === undefined ? {} : { advisory: clone(wire.advisory) }),
     ...(wire.prepared === null || wire.prepared === undefined ? {} : { prepared: clone(wire.prepared) }),
   };
@@ -690,6 +728,7 @@ export function makeStateCheckpoint(state: ActiveContextState): ActiveContextChe
     prepared: state.prepared ? clone(state.prepared) : null,
     tokensSinceToolFold: state.tokensSinceToolFold,
     leases: clone(state.leases),
+    ...(state.surfacing?.length ? { surfacing: clone(state.surfacing) } : {}),
     ...(state.advisory ? { advisory: clone(state.advisory) } : {}),
     stateSha256: semanticStateSha256(state),
   }, state.sessionId) as ActiveContextCheckpointV2;
@@ -724,6 +763,7 @@ export function makeStateDelta(previous: ActiveContextState, next: ActiveContext
     prepared: next.prepared ? clone(next.prepared) : null,
     tokensSinceToolFold: next.tokensSinceToolFold,
     leases: clone(next.leases),
+    ...(next.surfacing?.length ? { surfacing: clone(next.surfacing) } : {}),
     ...(next.advisory ? { advisory: clone(next.advisory) } : {}),
     stateSha256: semanticStateSha256(next),
   }, next.sessionId) as ActiveContextDeltaV2;
@@ -738,6 +778,7 @@ export function protectionSha256(state: Pick<ActiveContextState, "protected">):
 }
 
 export const ADVISORY_BUDGETS: Readonly<Record<AdvisoryMilestone, number>> = Object.freeze({
+  orientation: 1,
   notice: 2,
   tools: 2,
   chapters: 2,

package/extensions/lib/policy.ts

@@ -8,6 +8,9 @@ export const DEFAULT_ACTIVE_CONTEXT_COMMAND_NAMES = Object.freeze({
   status: "context",
   fold: "fold-context",
 });
+export const GUIDANCE_PROFILES = Object.freeze(["pressure", "curation", "minimal"] as const);
+export type GuidanceProfile = typeof GUIDANCE_PROFILES[number];
+export const DEFAULT_GUIDANCE_PROFILE: GuidanceProfile = "pressure";
 
 export function entryTypeNamespace(entryTypePrefix: string): string {
   const suffix = "-active-context";
@@ -37,7 +40,7 @@ export const NATIVE_COMPACTION_DECISION_ENTRY = `${DEFAULT_ENTRY_NAMESPACE}-nati
 export const PROVIDER_CONTEXT_MEASUREMENT_ENTRY = `${DEFAULT_ENTRY_NAMESPACE}-provider-context-measurement`;
 export const ACTIVE_CONTEXT_STATUS_KEY = DEFAULT_ACTIVE_CONTEXT_ENTRY_TYPE_PREFIX;
 export const ACTIVE_CONTEXT_TOOL_ACTIONS = Object.freeze([
-  "status", "fold", "expand", "refold", "protect", "unprotect",
+  "status", "peek", "fold", "expand", "refold", "protect", "unprotect",
 ] as const);
 export type ActiveContextToolAction = typeof ACTIVE_CONTEXT_TOOL_ACTIONS[number];
 export const USER_RESCUE_MAX_SOURCE_CHARS = 512_000;
@@ -49,8 +52,27 @@ export const MAX_EXPAND_LEASES = 64;
 export const CONSOLIDATION_WIDTH_THRESHOLD = 10;
 export const MAX_ADVISORY_DELIVERIES_PER_MILESTONE = 16;
 
+// Ephemeral surfacing structure. These stay INTERNAL constants rather than public
+// options: they are the knobs the surfacing experiment is meant to settle, and an
+// option surface fixed before the accept/reject data exists would freeze a guess.
+export const DEFAULT_SURFACING_ENABLED = true;
+export const SURFACING_TOP_K = 3;
+export const SURFACING_MIN_SCORE = 0.30;
+export const SURFACING_CHAR_BUDGET = 1_000;
+export const SURFACING_COOLDOWN_ORDINALS = 8;
+export const SURFACING_OUTCOME_WINDOW_ORDINALS = 12;
+export const SURFACING_RECENT_TASK_SPANS = 6;
+export const SURFACING_MAX_TASK_CHARS = 12_000;
+export const SURFACING_MAX_LOG_RECORDS = 128;
+export const SURFACING_LEXICAL_WEIGHT = 0.80;
+export const SURFACING_RECENCY_WEIGHT = 0.14;
+export const SURFACING_DEPTH_WEIGHT = 0.06;
+export const SURFACING_MAX_DEPTH = 4;
+export const SURFACING_MAX_TEXT_CHARS = 220;
+export const SURFACING_SOURCE_ID = "fold-brief";
+
 // Conservative LOWER bound on UTF-8 bytes per provider token, used only to cap
-// the protected byte tail as a share of a small window — never to estimate usage.
+// the protected byte tail as a share of a small window; never to estimate usage.
 export const BYTES_PER_TOKEN_FLOOR = 2;
 
 export const ACTIVE_CONTEXT_POLICY = Object.freeze({
@@ -120,6 +142,44 @@ export interface PreparedFold {
   fold: ActiveFold;
 }
 
+export type SurfacingOutcome = "shown" | "accept" | "reject";
+
+/** One durable surfacing observation: what was shown, how it scored, and what the agent did. */
+export interface SurfacingRecord {
+  source: string;
+  id: string;
+  score: number;
+  ordinal: number;
+  outcome: SurfacingOutcome;
+}
+
+/** One item a suggestion source offers for the shared carrier. */
+export interface SurfacingCandidate {
+  source: string;
+  id: string;
+  text: string;
+  route: string;
+  alternateRoute?: string;
+  /** Transcript position used for recency; higher is more recent. Never a wall clock. */
+  position?: number;
+  depth?: number;
+}
+
+export interface SurfacingSuggestion extends SurfacingCandidate {
+  score: number;
+}
+
+export interface SuggestionSourceInput {
+  state: ActiveContextState;
+  snapshot: ActiveContextSnapshot;
+  toolName: string;
+}
+
+export interface SuggestionSource {
+  id: string;
+  candidates: (input: SuggestionSourceInput) => SurfacingCandidate[];
+}
+
 export interface ActiveContextState {
   version: 1;
   sessionId: string;
@@ -129,6 +189,7 @@ export interface ActiveContextState {
   protected: EvidenceRef[];
   tokensSinceToolFold: number;
   leases: Record<string, number>;
+  surfacing?: SurfacingRecord[];
   prepared?: PreparedFold;
   advisory?: {
     highWater: number;
@@ -161,6 +222,7 @@ export interface ActiveContextCheckpointV2 {
   prepared: PreparedFold | null;
   tokensSinceToolFold?: number;
   leases?: Record<string, number>;
+  surfacing?: SurfacingRecord[];
   advisory?: NonNullable<ActiveContextState["advisory"]>;
   stateSha256: string;
 }
@@ -179,6 +241,7 @@ export interface ActiveContextDeltaV2 {
   prepared: PreparedFold | null;
   tokensSinceToolFold?: number;
   leases?: Record<string, number>;
+  surfacing?: SurfacingRecord[];
   advisory?: NonNullable<ActiveContextState["advisory"]>;
   stateSha256: string;
 }
@@ -230,4 +293,4 @@ export const READ_ONLY_TOOLS_DEFAULT = new Set([
   "read", "grep", "find", "ls",
 ]);
 
-export type AdvisoryMilestone = "notice" | "tools" | "chapters" | "urgent";
+export type AdvisoryMilestone = "orientation" | "notice" | "tools" | "chapters" | "urgent";