pi-fold 0.0.1 → 0.1.0

package/extensions/lib/selection.ts

@@ -0,0 +1,501 @@
+import type { EvidenceRef } from "../json.ts";
+import {
+  denseOwnArrayValues,
+  objectRefKey,
+} from "../json.ts";
+import {
+  bytes,
+  contentText,
+  messageRole,
+  ownValue,
+  usefulBrief,
+} from "./canonical.ts";
+import {
+  exactMapped,
+  foldInterval,
+  orderedRoots,
+  refsInOrder,
+  refsProtected,
+  toolFoldCadence,
+  toolRefsProtected,
+  visibleCollapsedRoots,
+} from "./measurement.ts";
+import {
+  flattenFoldRefs,
+  foldMap,
+} from "./persistence.ts";
+import {
+  ACTIVE_CONTEXT_POLICY,
+  CONSOLIDATION_WIDTH_THRESHOLD,
+  DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
+} from "./policy.ts";
+import type {
+  ActiveContextSnapshot,
+  ActiveContextState,
+  ActiveFold,
+  CompleteTurn,
+  FoldCandidate,
+  FoldKind,
+  FoldPart,
+  MappedMessage,
+} from "./policy.ts";
+import {
+  chapterSegments,
+  scanTurnToolBatches,
+  structurallyClosedChapterUnits,
+  terminalAssistant,
+} from "./transcript.ts";
+import type { ChapterUnit } from "./transcript.ts";
+
+export interface ResultCall {
+  id: string;
+  name: string;
+  batch: string[];
+  assistantIndex: number;
+}
+
+export const RESULT_CALL_INDEXES = new WeakMap<ActiveContextSnapshot, {
+  strict?: Map<number, ResultCall>;
+  consumed?: Map<number, ResultCall>;
+}>();
+
+export function resultCallIndex(snapshot: ActiveContextSnapshot, allowConsumedIncomplete: boolean): Map<number, ResultCall> {
+  const cached = RESULT_CALL_INDEXES.get(snapshot) ?? {};
+  const key = allowConsumedIncomplete ? "consumed" : "strict";
+  if (cached[key]) return cached[key]!;
+  const indexed = new Map<number, ResultCall>();
+  const segments: Array<{ turn: CompleteTurn; complete: boolean }> = snapshot.completeTurns.map((turn) => ({
+    turn,
+    complete: true,
+  }));
+  if (allowConsumedIncomplete) {
+    const completeStarts = new Set(snapshot.completeTurns.map((turn) => turn.start));
+    const starts = snapshot.messages.flatMap((message, index) => messageRole(message) === "user" ? [index] : []);
+    for (let cursor = 0; cursor < starts.length; cursor += 1) {
+      if (completeStarts.has(starts[cursor])) continue;
+      segments.push({
+        turn: { start: starts[cursor], end: starts[cursor + 1] ?? snapshot.messages.length },
+        complete: false,
+      });
+    }
+  }
+  segments.sort((left, right) => left.turn.start - right.turn.start);
+  for (const { turn, complete } of segments) {
+    const validated = scanTurnToolBatches(
+      snapshot.messages,
+      turn,
+      allowConsumedIncomplete,
+      snapshot.toolName,
+      snapshot.readOnlyTools,
+    );
+    if (!validated) continue;
+    const batches = new Map<number, string[]>();
+    for (const call of validated.calls) {
+      const batch = batches.get(call.assistantIndex) ?? [];
+      batch.push(call.id);
+      batches.set(call.assistantIndex, batch);
+    }
+    for (const call of validated.calls) {
+      if (allowConsumedIncomplete) {
+        let laterGenerations = 0;
+        for (let index = call.resultIndex + 1; index < turn.end; index += 1) {
+          const message = snapshot.messages[index];
+          if (messageRole(message) !== "assistant") continue;
+          if (ownValue(message, "stopReason") === "toolUse") laterGenerations += 1;
+          else if (complete && terminalAssistant(message)) laterGenerations = Math.max(laterGenerations, 1);
+        }
+        if ((complete && laterGenerations < 1) || (!complete && laterGenerations < 2)) continue;
+      }
+      indexed.set(call.resultIndex, {
+        id: call.id,
+        name: call.name,
+        assistantIndex: call.assistantIndex,
+        batch: batches.get(call.assistantIndex)!,
+      });
+    }
+  }
+  cached[key] = indexed;
+  RESULT_CALL_INDEXES.set(snapshot, cached);
+  return indexed;
+}
+
+export function resultCall(
+  snapshot: ActiveContextSnapshot,
+  resultIndex: number,
+  allowConsumedIncomplete = false,
+): ResultCall | null {
+  return resultCallIndex(snapshot, allowConsumedIncomplete).get(resultIndex) ?? null;
+}
+
+export const TOOL_CALL_ARGUMENTS = new WeakMap<ActiveContextSnapshot, Map<number, Map<string, unknown>>>();
+
+export function toolCallArguments(snapshot: ActiveContextSnapshot, assistantIndex: number, id: string): unknown {
+  let assistants = TOOL_CALL_ARGUMENTS.get(snapshot);
+  if (!assistants) {
+    assistants = new Map();
+    TOOL_CALL_ARGUMENTS.set(snapshot, assistants);
+  }
+  let calls = assistants.get(assistantIndex);
+  if (!calls) {
+    calls = new Map();
+    const assistant = snapshot.messages[assistantIndex];
+    for (const part of denseOwnArrayValues(ownValue(assistant, "content")) ?? []) {
+      if (ownValue(part, "type") !== "toolCall") continue;
+      const callId = ownValue(part, "id");
+      if (typeof callId === "string" && callId) calls.set(callId, ownValue(part, "arguments"));
+    }
+    assistants.set(assistantIndex, calls);
+  }
+  return calls.get(id);
+}
+
+export function automaticToolBrief(snapshot: ActiveContextSnapshot, candidate: FoldCandidate): string {
+  const refs = candidate.kind === "tool-result" && candidate.parts.every((part) => part.kind === "raw")
+    ? candidate.parts.map((part) => (part as Extract<FoldPart, { kind: "raw" }>).ref)
+    : [];
+  const calls = refs.map((ref) => {
+    const item = exactMapped(snapshot, ref);
+    const call = item ? resultCall(snapshot, item.index, true) : null;
+    if (!call) throw new Error("Automatic tool brief lost its validated call");
+    return call;
+  });
+  if (!calls.length || new Set(calls.map((call) => call.assistantIndex)).size !== 1) {
+    throw new Error("Automatic tool brief crossed a validated assistant batch");
+  }
+  const first = calls[0];
+  const factualBriefValue = (value: string): string => value
+    .replace(new RegExp(snapshot.toolName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi"), "active-context service")
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 120);
+  const factualToolName = (name: string): string => name.toLowerCase() === snapshot.toolName.toLowerCase()
+    ? "active-context status inspection"
+    : factualBriefValue(name);
+  const args = toolCallArguments(snapshot, first.assistantIndex, first.id);
+  const targets: string[] = [];
+  for (const key of ["path", "address", "query", "url", "action", "id"]) {
+    const value = ownValue(args, key);
+    if (typeof value === "string" && value.trim()) targets.push(`${key}=${factualBriefValue(value)}`);
+  }
+  const target = targets.length ? ` for ${targets.join(", ")}` : "";
+  if (calls.length === 1) {
+    return `Completed read-only ${factualToolName(first.name)}${target}; its exact stale output remains recoverable from this fold.`;
+  }
+  const names = [...new Set(calls.map((call) => factualToolName(call.name)))].sort().join("/");
+  return `Completed one read-only ${names} batch with ${calls.length} exact results${target}; every stale output remains recoverable from this fold.`;
+}
+
+export function deterministicConsolidationBrief(candidate: FoldCandidate, state: ActiveContextState): string {
+  const byId = foldMap(state);
+  const subjects = candidate.parts.flatMap((part) => {
+    if (part.kind !== "fold") return [];
+    const child = byId.get(part.foldId);
+    return child ? [child.brief.replace(/\s+/g, " ").trim()] : [];
+  });
+  const text = `Grouped completed context covering: ${subjects.join(" ")}`.replace(/\s+/g, " ").trim();
+  if (text.length <= ACTIVE_CONTEXT_POLICY.maxBriefChars) return text;
+  let bounded = text.slice(0, ACTIVE_CONTEXT_POLICY.maxBriefChars - 1).trimEnd();
+  const finalCode = bounded.charCodeAt(bounded.length - 1);
+  if (finalCode >= 0xd800 && finalCode <= 0xdbff) bounded = bounded.slice(0, -1);
+  return `${bounded}.`;
+}
+
+export function partsForRange(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  start: number,
+  end: number,
+  allowedChildKinds: ReadonlySet<FoldKind>,
+): FoldPart[] | null {
+  const roots = orderedRoots(state, snapshot);
+  for (const root of roots) {
+    const overlaps = root.start <= end && start <= root.end;
+    if (!overlaps) continue;
+    if (root.start < start || root.end > end || !allowedChildKinds.has(root.fold.kind)) return null;
+  }
+  const childAt = new Map(roots
+    .filter((root) => root.start >= start && root.end <= end)
+    .map((root) => [root.start, root]));
+  const parts: FoldPart[] = [];
+  for (let index = start; index <= end;) {
+    const child = childAt.get(index);
+    if (child) {
+      parts.push({ kind: "fold", foldId: child.fold.id });
+      index = child.end + 1;
+      continue;
+    }
+    const ref = snapshot.mapped[index]?.ref;
+    if (!ref) return null;
+    parts.push({ kind: "raw", ref });
+    index += 1;
+  }
+  return parts;
+}
+
+export function candidateSourceRefs(parts: FoldPart[], state: ActiveContextState): EvidenceRef[] {
+  const byId = foldMap(state);
+  return parts.flatMap((part) => {
+    if (part.kind === "raw") return [part.ref];
+    const child = byId.get(part.foldId);
+    if (!child) throw new Error(`Missing candidate child ${part.foldId}`);
+    return flattenFoldRefs(child, state);
+  });
+}
+
+export function chapterUnits(snapshot: ActiveContextSnapshot): ChapterUnit[] {
+  return chapterSegments(snapshot.messages)
+    .flatMap((segment) => structurallyClosedChapterUnits(snapshot.messages, segment));
+}
+
+export function selectAutomaticConsolidation(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ratio: number,
+): FoldCandidate | null {
+  const visibleRoots = visibleCollapsedRoots(state, snapshot);
+  const widthEligible = visibleRoots.length > CONSOLIDATION_WIDTH_THRESHOLD;
+  const pressureEligible = Number.isFinite(ratio) && ratio >= snapshot.policy.consolidationRatio;
+  if (!widthEligible && !pressureEligible) return null;
+  const roots = visibleRoots.filter(({ fold }) =>
+    (fold.kind === "chapter" || fold.kind === "consolidation") &&
+    !refsProtected(flattenFoldRefs(fold, state), state, snapshot));
+  const candidateFor = (selected: typeof roots): FoldCandidate | null => {
+    const parts: FoldPart[] = selected.map(({ fold }) => ({ kind: "fold", foldId: fold.id }));
+    const sourceRefs = candidateSourceRefs(parts, state);
+    return selected.length >= 2 && sourceRefs.length <= snapshot.policy.maxFoldSourceRefs
+      ? { kind: "consolidation", parts, sourceRefs }
+      : null;
+  };
+  if (widthEligible && !pressureEligible) {
+    const oldest = roots.slice(0, snapshot.policy.consolidationChildren);
+    let run: typeof roots = [];
+    for (const root of oldest) {
+      if (!run.length || root.start === run.at(-1)!.end + 1) {
+        run.push(root);
+      } else {
+        if (run.length >= 2) return candidateFor(run);
+        run = [root];
+      }
+    }
+    return run.length >= 2 ? candidateFor(run) : null;
+  }
+  let run: typeof roots = [];
+  const finish = (): FoldCandidate | null => {
+    if (run.length < snapshot.policy.consolidationChildren) return null;
+    const selected = run.slice(0, snapshot.policy.maxConsolidationChildren);
+    const parts: FoldPart[] = selected.map(({ fold }) => ({ kind: "fold", foldId: fold.id }));
+    const sourceRefs = candidateSourceRefs(parts, state);
+    return sourceRefs.length <= snapshot.policy.maxFoldSourceRefs
+      ? { kind: "consolidation", parts, sourceRefs }
+      : null;
+  };
+  for (const root of roots) {
+    if (!run.length || root.start === run.at(-1)!.end + 1) run.push(root);
+    else {
+      const candidate = finish();
+      if (candidate) return candidate;
+      run = [root];
+    }
+  }
+  return finish();
+}
+
+export function selectAutomaticToolBatch(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ratio: number,
+): FoldCandidate[] {
+  if (!Number.isFinite(ratio) || ratio < snapshot.policy.toolFoldRatio) return [];
+  const owned = new Set(state.folds.flatMap((fold) => fold.parts.flatMap((part) =>
+    part.kind === "raw" ? [objectRefKey(part.ref)] : [])));
+  const groups = new Map<number, Array<{ item: MappedMessage; call: NonNullable<ReturnType<typeof resultCall>> }>>();
+  for (const item of snapshot.mapped) {
+    if (messageRole(item.message) !== "toolResult") continue;
+    const call = resultCall(snapshot, item.index, true);
+    if (!call) continue;
+    const group = groups.get(call.assistantIndex) ?? [];
+    group.push({ item, call });
+    groups.set(call.assistantIndex, group);
+  }
+  for (const group of groups.values()) {
+    const expected = group[0].call.batch;
+    const ids = new Set(group.map(({ call }) => call.id));
+    const refs = group.map(({ item }) => item.ref);
+    if (ids.size !== expected.length || expected.some((id) => !ids.has(id)) ||
+        refs.some((ref) => !ref || ref.role !== "toolResult")) continue;
+    const exactRefs = refs as EvidenceRef[];
+    if (exactRefs.length > snapshot.policy.maxFoldSourceRefs ||
+        exactRefs.some((ref) => owned.has(objectRefKey(ref))) ||
+        toolRefsProtected(exactRefs, state, snapshot) || refsInOrder(snapshot, exactRefs) === null ||
+        group.reduce((total, { item }) => total + bytes(item.message), 0) < snapshot.policy.minToolChars) continue;
+    return [{
+      kind: "tool-result",
+      parts: exactRefs.map((ref) => ({ kind: "raw", ref })),
+      sourceRefs: exactRefs,
+    }];
+  }
+  return [];
+}
+
+export function selectAutomaticRefold(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ratio: number,
+): string | null {
+  if (!Number.isFinite(ratio) || ratio < snapshot.policy.refoldRatio) return null;
+  const candidates = state.expanded.flatMap((id) => {
+    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));
+    return fold && interval && !protectedSource && !state.leases[id] ? [{ id, ...interval }] : [];
+  }).sort((left, right) => left.end - right.end || (left.end - left.start) - (right.end - right.start));
+  return candidates[0]?.id ?? null;
+}
+
+export function selectAutomaticToolForRung(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ratio: number,
+  cadenceWaived = false,
+): FoldCandidate | null {
+  const cadenceSatisfied = state.tokensSinceToolFold >= toolFoldCadence(snapshot.contextWindow);
+  if (!cadenceWaived && (!Number.isFinite(ratio) ||
+      (ratio < snapshot.policy.toolFoldRatio && !cadenceSatisfied))) return null;
+  return selectAutomaticToolBatch(snapshot, state, 1)[0] ?? null;
+}
+
+export function resolveFoldInputIds(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ids: string[],
+): Array<{ start: number; end: number; fold?: ActiveFold }> {
+  if (!ids.length || ids.length > 64 || ids.some((id) => !id)) throw new Error("fold requires 1-64 nonempty ids");
+  const values = ids.map((id) => {
+    const fold = state.folds.find((item) => item.id === id);
+    if (fold) {
+      if (fold.parentId !== null) throw new Error(`Fold ${id} is already nested under ${fold.parentId}`);
+      const interval = foldInterval(fold, state, snapshot);
+      if (!interval) throw new Error(`Fold ${id} is not active in the Pi context event`);
+      return { ...interval, fold };
+    }
+    const item = snapshot.mapped.find((candidate) => candidate.ref?.entryId === id);
+    if (!item?.ref) throw new Error(`Unknown active-context source ${id}`);
+    return { start: item.index, end: item.index };
+  });
+  values.sort((left, right) => left.start - right.start);
+  return values;
+}
+
+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 manualFoldCandidate(
+  snapshot: ActiveContextSnapshot,
+  state: ActiveContextState,
+  ids: string[],
+): FoldCandidate {
+  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`);
+    }
+    return candidate;
+  };
+  const selected = resolveFoldInputIds(snapshot, state, ids);
+  const start = selected[0].start;
+  const end = selected.at(-1)!.end;
+  const one = selected.length === 1 ? selected[0] : null;
+  if (selected.every((item) => !item.fold && snapshot.mapped[item.start].ref?.role === "toolResult")) {
+    const refs = selected.map((item) => snapshot.mapped[item.start].ref!);
+    const calls = selected.map((item) => resultCall(snapshot, item.start, true));
+    const first = calls[0];
+    const completeBatch = first && calls.every((call) => call && call.assistantIndex === first.assistantIndex) &&
+      calls.length === first.batch.length &&
+      new Set(calls.map((call) => call!.id)).size === first.batch.length &&
+      first.batch.every((id) => calls.some((call) => call!.id === id));
+    if (completeBatch && !toolRefsProtected(refs, state, snapshot)) {
+      return bounded({ kind: "tool-result", parts: refs.map((ref) => ({ kind: "raw", ref })), sourceRefs: refs });
+    }
+    if (one && first && first.batch.length === 1 && !toolRefsProtected(refs, state, snapshot)) {
+      return bounded({ kind: "tool-result", parts: [{ kind: "raw", ref: refs[0] }], sourceRefs: refs });
+    }
+  }
+  const exactFolds = selected.every((item) => item.fold && item.fold.kind !== "tool-result") &&
+    selected.every((item, index) => index === 0 || item.start === selected[index - 1].end + 1);
+  if (exactFolds && selected.length >= 2) {
+    const parts: FoldPart[] = selected.map((item) => ({ kind: "fold", foldId: item.fold!.id }));
+    const refs = candidateSourceRefs(parts, state);
+    if (refsProtected(refs, state, snapshot)) throw new Error("Manual consolidation contains protected evidence");
+    return bounded({ kind: "consolidation", parts, sourceRefs: refs });
+  }
+  if (!chapterRangeIsUnitAligned(snapshot, start, end)) {
+    throw new Error("Chapter folds must align to a contiguous structurally closed user/assistant/tool-batch range");
+  }
+  const parts = partsForRange(snapshot, state, start, end, new Set<FoldKind>(["tool-result"]));
+  if (!parts) throw new Error("Chapter fold would partially overlap or swallow an existing chapter");
+  const refs = candidateSourceRefs(parts, state);
+  if (refsProtected(refs, state, snapshot)) throw new Error("Manual chapter contains fresh, unfinished, unmatched, unmapped, or protected evidence");
+  return bounded({ kind: "chapter", parts, sourceRefs: refs });
+}
+
+export function oneLine(value: string, maximum: number): string {
+  const text = value.replace(/\s+/g, " ").trim();
+  if (text.length <= maximum) return text;
+  let bounded = text.slice(0, maximum).trimEnd();
+  const finalCode = bounded.charCodeAt(bounded.length - 1);
+  if (finalCode >= 0xd800 && finalCode <= 0xdbff) bounded = bounded.slice(0, -1);
+  return bounded;
+}
+
+export function deterministicChapterBrief(
+  refs: EvidenceRef[],
+  messages: unknown[],
+  toolName = DEFAULT_ACTIVE_CONTEXT_TOOL_NAME,
+): string {
+  if (refs.length !== messages.length || !refs.length) {
+    throw new Error("Deterministic chapter brief requires aligned exact evidence");
+  }
+  const firstUser = messages.find((message) => messageRole(message) === "user");
+  const firstAssistant = messages.find((message) =>
+    messageRole(message) === "assistant" && contentText(message).trim());
+  const toolCounts = new Map<string, number>();
+  for (const message of messages) {
+    if (messageRole(message) !== "assistant") continue;
+    for (const part of denseOwnArrayValues(ownValue(message, "content")) ?? []) {
+      if (ownValue(part, "type") !== "toolCall") continue;
+      const name = ownValue(part, "name");
+      if (typeof name === "string" && name) toolCounts.set(name, (toolCounts.get(name) ?? 0) + 1);
+    }
+  }
+  const ask = oneLine(firstUser ? contentText(firstUser) : "No user ask in this span", 90);
+  const assistant = oneLine(firstAssistant ? contentText(firstAssistant).split(/\r?\n/)[0] :
+    "No assistant text in this span", 110);
+  const tools = oneLine([...toolCounts.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, count]) => `${count}×${name}`)
+    .join(" ") || "no tools", 500);
+  const escapeName = (name: string) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const composed = `User: ${ask} · Tools: ${tools} · Assistant: ${assistant}`
+    .replace(new RegExp(escapeName(toolName), "gi"), "active-context service");
+  if (usefulBrief(composed, ACTIVE_CONTEXT_POLICY.maxBriefChars, toolName)) return composed;
+  // Constant floor-of-the-floor: provably passes usefulBrief (no tool name, no structural pattern).
+  return `Folded ${refs.length} exact messages from this span's complete turns.`;
+}
+
+export function deterministicChapterCandidateBrief(
+  snapshot: ActiveContextSnapshot,
+  candidate: FoldCandidate,
+): string {
+  const messages = candidate.sourceRefs.map((ref) => {
+    const item = exactMapped(snapshot, ref);
+    if (!item) throw new Error(`Exact Pi evidence drift for ${ref.entryId}`);
+    return item.message;
+  });
+  return deterministicChapterBrief(candidate.sourceRefs, messages, snapshot.toolName);
+}

package/extensions/lib/tool-surface.ts

@@ -0,0 +1,66 @@
+type ToolHandler = (
+  toolCallId: string,
+  params: Record<string, unknown>,
+  signal: AbortSignal,
+  onUpdate: unknown,
+  ctx: any,
+) => Promise<unknown>;
+
+type CommandHandler = (args: string, ctx: any) => Promise<void> | void;
+
+export function buildActiveContextTool(input: {
+  name: string;
+  label: string;
+  allowedActions: readonly string[];
+  fullSurface: boolean;
+  maxBriefChars: number;
+  handler: ToolHandler;
+}) {
+  return {
+    name: input.name,
+    label: input.label,
+    description: input.fullSurface
+      ? "Page, fold, expand, refold, or protect exact Pi active-context evidence. 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(", ")}. 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,
+      required: ["action"],
+      properties: {
+        action: { type: "string", enum: input.allowedActions },
+        ids: { type: "array", minItems: 1, maxItems: 64, items: { type: "string", minLength: 1 } },
+        id: { type: "string", minLength: 1 },
+        brief: {
+          type: "string",
+          minLength: 1,
+          maxLength: input.maxBriefChars,
+          description: "Factual fold brief; keep it at most 1000 characters to stay below the hard 1200-character limit.",
+        },
+        offset: { type: "integer", minimum: 0 },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+        detail: { type: "string", enum: ["fold_candidates"] },
+      },
+    },
+    execute: input.handler,
+  };
+}
+
+export function buildActiveContextCommands(input: {
+  statusName: string;
+  foldName: string;
+  statusHandler: CommandHandler;
+  foldHandler: CommandHandler;
+}) {
+  return [
+    {
+      name: input.statusName,
+      description: "Show active-context fold roots and paging state",
+      handler: input.statusHandler,
+    },
+    {
+      name: input.foldName,
+      description: "Losslessly fold a stale context span; works without a main-model request",
+      handler: input.foldHandler,
+    },
+  ];
+}