@criogaid/pi-codex-compaction 0.3.0

package/src/context-window.ts

@@ -0,0 +1,108 @@
+// Own Codex's pre-compaction tool-output trimming and its model-visible item estimate.
+// Reference: openai/codex rust-v0.159.2, compact_remote_history.rs and context_manager/history.rs.
+import { type ImageEstimates, RESIZED_IMAGE_BYTES_ESTIMATE } from "./image-budget.js";
+import { isInputImage, isObject, type JsonObject } from "./protocol.js";
+import { historyGroups, type HistoryGroup } from "./history-groups.js";
+import { approximateTokenCount, approximateTokensFromBytes } from "./text-budget.js";
+
+const EFFECTIVE_CONTEXT_WINDOW_PERCENT = 95;
+const DEFAULT_FUNCTION_NAMESPACE = "functions";
+const TRUNCATED_OUTPUT_MESSAGE = "Output exceeded the available model context and was truncated";
+
+function textBytes(value: unknown): number {
+  return typeof value === "string" ? Buffer.byteLength(value, "utf8") : 0;
+}
+function jsonBytes(value: unknown): number {
+  const json = value === undefined || value === null ? undefined : JSON.stringify(value);
+  return json === undefined ? 0 : Buffer.byteLength(json, "utf8");
+}
+function reasoningBytes(value: unknown): number {
+  return typeof value === "string" ? Math.max(0, Math.floor(textBytes(value) * 3 / 4) - 650) : 0;
+}
+function partBytes(part: unknown, images: ImageEstimates): number {
+  if (!isObject(part)) return 0;
+  if (part.type === "input_text" || part.type === "output_text") return textBytes(part.text);
+  if (part.type === "encrypted_content") return Math.ceil(textBytes(part.encrypted_content) * 9 / 16);
+  // Pi sends no audio parts.
+  return isInputImage(part) ? images.bytes(part) : 0;
+}
+function contentBytes(content: unknown, images: ImageEstimates): number {
+  if (typeof content === "string") return textBytes(content);
+  return Array.isArray(content) ? content.reduce((sum: number, part: unknown) => sum + partBytes(part, images), 0) : 0;
+}
+
+function itemBytes(item: JsonObject, images: ImageEstimates): number {
+  switch (item.type ?? "message") {
+    case "message":
+      return contentBytes(item.content, images);
+    case "reasoning":
+    case "compaction":
+    case "compaction_summary":
+    case "context_compaction":
+      return reasoningBytes(item.encrypted_content);
+    case "function_call":
+      return textBytes(item.name) + textBytes(item.namespace ?? DEFAULT_FUNCTION_NAMESPACE) + textBytes(item.arguments);
+    case "custom_tool_call":
+      return textBytes(item.name) + textBytes(item.namespace ?? DEFAULT_FUNCTION_NAMESPACE) + textBytes(item.input);
+    case "function_call_output":
+      return contentBytes(item.output, images) + textBytes(item.call_id) + textBytes(item.name) + textBytes(item.namespace);
+    case "custom_tool_call_output":
+      return contentBytes(item.output, images) + textBytes(item.call_id) + textBytes(item.name);
+    case "additional_tools":
+    case "tool_search_output":
+      return jsonBytes(item.tools);
+    case "tool_search_call":
+      return jsonBytes(item.arguments);
+    case "local_shell_call":
+    case "web_search_call":
+      return jsonBytes(item.action);
+    case "image_generation_call":
+      return textBytes(item.revised_prompt) + (textBytes(item.result) > 0 ? RESIZED_IMAGE_BYTES_ESTIMATE : 0);
+    default:
+      return 0;
+  }
+}
+
+export function itemTokenCount(item: JsonObject, images: ImageEstimates): number {
+  return approximateTokensFromBytes(itemBytes(item, images));
+}
+function groupTokenCount({ source, notice }: HistoryGroup, images: ImageEstimates): number {
+  return itemTokenCount(source, images) + (notice ? itemTokenCount(notice, images) : 0);
+}
+
+function rewrittenOutput(item: JsonObject): JsonObject | undefined {
+  if (item.type === "function_call_output" || item.type === "custom_tool_call_output") {
+    return { ...item, output: TRUNCATED_OUTPUT_MESSAGE };
+  }
+  return item.type === "tool_search_output" ? { ...item, tools: [] } : undefined;
+}
+
+/**
+ * Replace trailing tool outputs until the estimate fits Codex's usable window.
+ * A replaced output drops its attached notice; the first non-output group stops trimming.
+ */
+export function trimToolOutputsToContextWindow(
+  input: readonly JsonObject[],
+  instructions: unknown,
+  contextWindow: number,
+  images: ImageEstimates,
+): JsonObject[] {
+  if (!Number.isFinite(contextWindow) || contextWindow <= 0) return [...input];
+  const usableWindow = Math.floor(contextWindow * EFFECTIVE_CONTEXT_WINDOW_PERCENT / 100);
+  const groups = historyGroups(input);
+  let estimated = groups.reduce(
+    (sum, group) => sum + groupTokenCount(group, images),
+    approximateTokenCount(typeof instructions === "string" ? instructions : ""),
+  );
+  let consumed = 0;
+  const rewritten: JsonObject[] = [];
+  for (let index = groups.length - 1; index >= 0 && estimated > usableWindow; index--) {
+    const group = groups[index];
+    const replacement = rewrittenOutput(group.source);
+    if (!replacement) break;
+    estimated += itemTokenCount(replacement, images) - groupTokenCount(group, images);
+    consumed += group.notice ? 2 : 1;
+    rewritten.push(replacement);
+  }
+  return [...input.slice(0, input.length - consumed), ...rewritten.reverse()];
+}

package/src/fallback-command.ts

@@ -0,0 +1,189 @@
+// Own compaction settings interaction; use Pi widgets without changing the session's model or thinking level.
+import { getSupportedThinkingLevels, type Api, type Model } from "@earendil-works/pi-ai";
+import { getSelectListTheme, getSettingsListTheme, type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Container, fuzzyFilter, Input, SelectList, SettingsList, Text } from "@earendil-works/pi-tui";
+import { loadCompactionSettings, type FallbackConfiguration } from "./fallback-settings.js";
+
+const COMMAND_NAME = "codex-compaction";
+const SUMMARY_SWITCH_LABEL = "Use separate summary model";
+const SUMMARY_MODEL_LABEL = "Summary model and thinking level";
+const TEXT_SUMMARY_DESCRIPTION = "Text summaries are used when V2 is off, unsupported, or fails.";
+const MAX_VISIBLE_MODELS = 10;
+type SettingsAction = "model" | "toggle" | "remote";
+
+/** A fallback that failed validation stays editable: V2 can still be toggled and a new model replaces it. */
+type FallbackState =
+  | { readonly value: FallbackConfiguration | undefined; readonly error?: never }
+  | { readonly value?: never; readonly error: string };
+
+function readFallback(read: () => FallbackConfiguration | undefined): FallbackState {
+  try {
+    return { value: read() };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function fallbackModelLabel(selection: FallbackConfiguration | undefined): string | undefined {
+  return selection?.model === undefined ? undefined : `${selection.provider}/${selection.model} (${selection.thinkingLevel})`;
+}
+
+function describeFallback(selection: FallbackConfiguration | undefined): string {
+  const model = fallbackModelLabel(selection);
+  if (model === undefined) return "No separate summary model configured; inactive. Pi uses the chat model.";
+  return selection?.enabled ? `Text summaries will use ${model}. The chat model is unchanged.`
+    : `Separate summary model is Off. Pi will use the chat model for text compaction. Saved model: ${model}.`;
+}
+
+async function chooseAction(
+  ctx: ExtensionCommandContext,
+  remoteCompactionEnabled: boolean,
+  fallback: FallbackState,
+  selected: SettingsAction,
+): Promise<SettingsAction | undefined> {
+  const current = fallback.value;
+  const invalid = fallback.error !== undefined;
+  const description = fallback.error ?? `${TEXT_SUMMARY_DESCRIPTION} ${describeFallback(current)}`;
+  const remoteValue = remoteCompactionEnabled ? "On" : "Off";
+  const switchValue = invalid ? "Invalid" : current?.enabled ? "On" : "Off";
+  if (ctx.mode !== "tui") {
+    const switchLabel = `${SUMMARY_SWITCH_LABEL}: ${switchValue}`;
+    const remoteLabel = `Remote Compaction V2: ${remoteValue}`;
+    const action = await ctx.ui.select(description, [remoteLabel, switchLabel, SUMMARY_MODEL_LABEL]);
+    if (action === undefined) return undefined;
+    if (action === SUMMARY_MODEL_LABEL) return "model";
+    if (action === switchLabel) return "toggle";
+    if (action === remoteLabel) return "remote";
+    throw new Error("Select a listed compaction setting");
+  }
+  return ctx.ui.custom<SettingsAction | undefined>((tui, _theme, _keys, done) => {
+    const list = new SettingsList([
+      { id: "remote", label: "Remote Compaction V2", currentValue: remoteValue, values: ["Off", "On"], description: "When On, try V2 with the chat model. When Off, unsupported, or failed, use text summaries. The settings below choose their model. Turning V2 off does not affect previously compressed chat history." },
+      { id: "toggle", label: SUMMARY_SWITCH_LABEL, currentValue: switchValue, values: invalid ? ["Invalid"] : ["Off", "On"], description },
+      { id: "model", label: SUMMARY_MODEL_LABEL, currentValue: invalid ? "Invalid" : fallbackModelLabel(current) ?? "Not configured", values: ["Choose"], description: invalid ? "Choose a model to replace the invalid fallback settings." : `Choose the model and thinking level used when "${SUMMARY_SWITCH_LABEL}" is On. Choosing a model does not enable the switch or change the chat model. ${TEXT_SUMMARY_DESCRIPTION}` },
+    ], 3, getSettingsListTheme(), (id) => done(id === "toggle" ? "toggle" : id === "remote" ? "remote" : "model"), () => done(undefined));
+    list.selectItem(selected);
+    return {
+      render: (width) => list.render(width),
+      invalidate: () => list.invalidate(),
+      handleInput: (data) => { list.handleInput(data); tui.requestRender(); },
+    };
+  });
+}
+
+function modelLabel(model: Model<Api>): string {
+  return `${model.provider}/${model.id} (${model.name})`;
+}
+
+async function chooseModel(ctx: ExtensionCommandContext, models: readonly Model<Api>[]): Promise<Model<Api> | undefined> {
+  if (ctx.mode !== "tui") {
+    const query = await ctx.ui.input("Search summary models (provider, ID, or name)", "Leave empty to show all models");
+    if (query === undefined) return undefined;
+    const matches = fuzzyFilter([...models], query, modelLabel);
+    const chosen = await ctx.ui.select("Choose the model for text summaries", matches.map(modelLabel));
+    if (chosen === undefined) return undefined;
+    const model = matches.find((candidate) => modelLabel(candidate) === chosen);
+    if (!model) throw new Error("Select a listed fallback model");
+    return model;
+  }
+  return ctx.ui.custom<Model<Api> | undefined>((tui, _theme, keys, done) => {
+    const input = new Input();
+    const container = new Container();
+    let list: SelectList;
+    const update = () => {
+      const matches = fuzzyFilter([...models], input.getValue(), modelLabel);
+      list = new SelectList(matches.map((model, index) => ({ value: String(index), label: model.id, description: `${model.provider} · ${model.name}` })), MAX_VISIBLE_MODELS, getSelectListTheme());
+      list.onSelect = (item) => done(matches[Number(item.value)]);
+      list.onCancel = () => done(undefined);
+      container.clear();
+      container.addChild(new Text("Summary model: type to search by provider, ID, or name", 0, 0));
+      container.addChild(input);
+      container.addChild(list);
+    };
+    update();
+    return {
+      get focused() { return input.focused; },
+      set focused(value: boolean) { input.focused = value; },
+      render: (width) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput(data) {
+        if ((["tui.select.up", "tui.select.down", "tui.select.confirm", "tui.select.cancel"] as const).some((action) => keys.matches(data, action))) {
+          list.handleInput(data);
+        } else {
+          input.handleInput(data);
+          update();
+        }
+        tui.requestRender();
+      },
+    };
+  });
+}
+
+async function configureCompaction(path: string, ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) {
+    ctx.ui.notify(`/${COMMAND_NAME} requires interactive or RPC mode; edit ${path} directly.`, "warning");
+    return;
+  }
+  let selected: SettingsAction = "remote";
+  while (true) {
+    const settings = await loadCompactionSettings(path);
+    const configuration = settings.configuration;
+    const fallback = readFallback(() => configuration.fallback);
+    const current = fallback.value;
+    const action = await chooseAction(ctx, configuration.remoteCompactionEnabled, fallback, selected);
+    if (action === undefined) return;
+    selected = action;
+    if (action === "remote") {
+      const remoteCompactionEnabled = !configuration.remoteCompactionEnabled;
+      // Save a valid fallback in normalized form; omit an invalid one so the file keeps it as written.
+      await settings.save(fallback.error === undefined ? { remoteCompactionEnabled, fallback: current } : { remoteCompactionEnabled });
+      ctx.ui.notify(remoteCompactionEnabled
+        ? "Remote Compaction V2 is On. Supported models try V2 before text fallback."
+        : "Remote Compaction V2 is Off. Text compaction uses the configured fallback when enabled; otherwise Pi uses the chat model.", "info");
+    } else if (action === "toggle" && fallback.error !== undefined) {
+      ctx.ui.notify(`${fallback.error}. Choose a model to replace it, or edit the file directly.`, "error");
+    } else if (action === "toggle") {
+      const selection = { ...current, enabled: !current?.enabled };
+      await settings.save({ remoteCompactionEnabled: configuration.remoteCompactionEnabled, fallback: selection });
+      ctx.ui.notify(describeFallback(selection), "info");
+    } else {
+      const models = [...ctx.modelRegistry.getAvailable()].sort((left, right) => {
+        const a = modelLabel(left);
+        const b = modelLabel(right);
+        return a < b ? -1 : a > b ? 1 : 0;
+      });
+      if (models.length === 0) {
+        ctx.ui.notify("No authenticated models are available. Configure a model in Pi first.", "warning");
+      } else {
+        const model = await chooseModel(ctx, models);
+        if (model !== undefined) {
+          const levels = getSupportedThinkingLevels(model);
+          const chosenLevel = await ctx.ui.select(`Thinking level for ${model.provider}/${model.id}`, [...levels]);
+          if (chosenLevel !== undefined) {
+            const thinkingLevel = levels.find((level) => level === chosenLevel);
+            if (thinkingLevel === undefined) throw new Error("Select a supported fallback thinking level");
+            const selection = { enabled: current?.enabled ?? false, provider: model.provider, model: model.id, thinkingLevel };
+            await settings.save({ remoteCompactionEnabled: configuration.remoteCompactionEnabled, fallback: selection });
+            ctx.ui.notify(describeFallback(selection), "info");
+          }
+        }
+      }
+    }
+    // TUI keeps the same row selected so repeated Enter presses toggle in place.
+    if (ctx.mode !== "tui") return;
+  }
+}
+
+export function registerCompactionCommand(pi: ExtensionAPI, path: string): void {
+  pi.registerCommand(COMMAND_NAME, {
+    description: "Configure V2 and fallback compaction settings",
+    handler: async (args, ctx) => {
+      try {
+        if (args.trim()) throw new Error(`Usage: /${COMMAND_NAME}`);
+        await configureCompaction(path, ctx);
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : "Could not configure compaction settings", "error");
+      }
+    },
+  });
+}

package/src/fallback-settings.ts

@@ -0,0 +1,181 @@
+// Own compaction settings, lazy fallback validation, and revision-bound file updates.
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { isObject } from "./protocol.js";
+
+export const COMPACTION_SETTINGS_RELATIVE_PATH = "extensions/pi-codex-compaction/config.json";
+const LEGACY_FALLBACK_ENABLED = true;
+export const DEFAULT_REMOTE_COMPACTION_ENABLED = true;
+const SETTINGS_VERSION = 1;
+const MAX_SETTINGS_BYTES = 16 * 1024;
+const DEFAULT_FILE_MODE = 0o600;
+const FILE_PERMISSION_MASK = 0o777;
+
+export type FallbackConfiguration = { readonly enabled: boolean } & (
+  | { readonly provider: string; readonly model: string; readonly thinkingLevel: string }
+  | { readonly provider?: never; readonly model?: never; readonly thinkingLevel?: never }
+);
+
+export interface CompactionConfiguration {
+  readonly remoteCompactionEnabled: boolean;
+  readonly fallback: FallbackConfiguration | undefined;
+}
+
+interface SettingsFile {
+  readonly bytes: Buffer | undefined;
+  readonly mode: number;
+}
+
+async function readSettingsFile(path: string): Promise<SettingsFile> {
+  let file;
+  try {
+    file = await open(path, "r");
+  } catch (error) {
+    if (isObject(error) && error.code === "ENOENT") return { bytes: undefined, mode: DEFAULT_FILE_MODE };
+    throw new Error(`Could not open compaction settings at ${path}`, { cause: error });
+  }
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile()) throw new Error("Compaction settings must be a regular file");
+    const bytes = Buffer.alloc(MAX_SETTINGS_BYTES + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const { bytesRead } = await file.read(bytes, length, bytes.length - length, length);
+      if (bytesRead === 0) break;
+      length += bytesRead;
+    }
+    if (length > MAX_SETTINGS_BYTES) throw new Error(`Compaction settings must not exceed ${MAX_SETTINGS_BYTES} bytes`);
+    return { bytes: bytes.subarray(0, length), mode: stat.mode & FILE_PERMISSION_MASK };
+  } catch (error) {
+    throw new Error(`Could not read compaction settings at ${path}; use a UTF-8 JSON object within ${MAX_SETTINGS_BYTES} bytes`, { cause: error });
+  } finally {
+    await file.close();
+  }
+}
+
+function settingsError(path: string, error: unknown): Error {
+  const reason = error instanceof SyntaxError || error instanceof TypeError ? "use a UTF-8 JSON object"
+    : error instanceof Error ? error.message : "invalid configuration";
+  return new Error(`Could not read compaction settings at ${path}; ${reason}`, { cause: error });
+}
+
+interface ParsedSettings {
+  readonly configuration: CompactionConfiguration;
+  /** The unvalidated fallback field, kept so saves that do not replace it preserve it as written. */
+  readonly rawFallback: { readonly value: unknown } | undefined;
+}
+
+function parseSettings(bytes: Buffer | undefined, path: string): ParsedSettings {
+  if (bytes === undefined) {
+    return { configuration: { remoteCompactionEnabled: DEFAULT_REMOTE_COMPACTION_ENABLED, fallback: undefined }, rawFallback: undefined };
+  }
+  // Accept a UTF-8 BOM, reject invalid bytes, and never echo file contents in errors.
+  const settings: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  if (!isObject(settings) || Object.keys(settings).some((key) => !["version", "remoteCompaction", "fallback"].includes(key))) {
+    throw new Error("Compaction settings must be an object with version and optional remoteCompaction and fallback fields");
+  }
+  if (("fallback" in settings || "remoteCompaction" in settings) && settings.version !== SETTINGS_VERSION) {
+    throw new Error(`version must be ${SETTINGS_VERSION} when compaction settings are configured`);
+  }
+  let remoteCompactionEnabled = DEFAULT_REMOTE_COMPACTION_ENABLED;
+  if ("remoteCompaction" in settings) {
+    const remote = settings.remoteCompaction;
+    if (!isObject(remote) || Object.keys(remote).some((key) => key !== "enabled") || typeof remote.enabled !== "boolean") {
+      throw new Error("remoteCompaction must be an object with a boolean enabled field");
+    }
+    remoteCompactionEnabled = remote.enabled;
+  }
+  let resolvedFallback: { readonly value: FallbackConfiguration | undefined } | undefined;
+  return {
+    configuration: {
+      remoteCompactionEnabled,
+      // Successful V2 requests do not need to resolve or validate fallback settings.
+      get fallback() {
+        try {
+          resolvedFallback ??= { value: "fallback" in settings ? parseFallback(settings.fallback) : undefined };
+        } catch (error) {
+          throw settingsError(path, error);
+        }
+        return resolvedFallback.value;
+      },
+    },
+    rawFallback: "fallback" in settings ? { value: settings.fallback } : undefined,
+  };
+}
+
+function parseFallback(fallback: unknown): FallbackConfiguration {
+  if (!isObject(fallback) || Object.keys(fallback).some((key) => !["enabled", "provider", "model", "thinkingLevel"].includes(key))) {
+    throw new Error("fallback must be an object with only enabled, provider, model, and thinkingLevel fields");
+  }
+  if ("enabled" in fallback && typeof fallback.enabled !== "boolean") {
+    throw new Error("fallback.enabled must be a boolean");
+  }
+  const enabled = typeof fallback.enabled === "boolean" ? fallback.enabled : LEGACY_FALLBACK_ENABLED;
+  if (!("provider" in fallback) && !("model" in fallback) && !("thinkingLevel" in fallback)) {
+    return { enabled };
+  }
+  if (typeof fallback.provider !== "string" || !fallback.provider.trim() || fallback.provider !== fallback.provider.trim()) {
+    throw new Error("fallback.provider must be a non-empty provider ID without surrounding whitespace");
+  }
+  if (typeof fallback.model !== "string" || !fallback.model.trim() || fallback.model !== fallback.model.trim()) {
+    throw new Error("fallback.model must be a non-empty model ID without surrounding whitespace");
+  }
+  if (typeof fallback.thinkingLevel !== "string" || !fallback.thinkingLevel.trim()) {
+    throw new Error("fallback.thinkingLevel must be a non-empty thinking level");
+  }
+  return {
+    enabled,
+    provider: fallback.provider, model: fallback.model, thinkingLevel: fallback.thinkingLevel,
+  };
+}
+
+/**
+ * Capture one revision; reading configuration.fallback validates it on demand and can throw.
+ * Saving detects edits before atomic replacement; a selection without a fallback field keeps the file's fallback as written.
+ */
+export async function loadCompactionSettings(path: string) {
+  const original = await readSettingsFile(path);
+  let parsed: ParsedSettings;
+  try {
+    parsed = parseSettings(original.bytes, path);
+  } catch (error) {
+    throw settingsError(path, error);
+  }
+  const { configuration, rawFallback } = parsed;
+  return {
+    configuration,
+    async save(selection: { readonly remoteCompactionEnabled: boolean; readonly fallback?: FallbackConfiguration | undefined }): Promise<void> {
+      const fallback = "fallback" in selection ? selection.fallback : rawFallback?.value;
+      await withFileMutationQueue(path, async () => {
+        await mkdir(dirname(path), { recursive: true });
+        const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+        const bytes = Buffer.from(`${JSON.stringify({
+          version: SETTINGS_VERSION,
+          remoteCompaction: { enabled: selection.remoteCompactionEnabled },
+          ...(fallback === undefined ? {} : { fallback }),
+        }, null, 2)}\n`);
+        if (bytes.length > MAX_SETTINGS_BYTES) throw new Error(`Compaction settings must not exceed ${MAX_SETTINGS_BYTES} bytes`);
+        try {
+          await writeFile(temporary, bytes, { flag: "wx", mode: original.mode });
+          const current = await readSettingsFile(path);
+          if (original.bytes === undefined ? current.bytes !== undefined : !current.bytes?.equals(original.bytes)) {
+            throw new Error("Compaction settings changed while the menu was open; reopen /codex-compaction and try again");
+          }
+          // Reading follows existing symlinks; an atomic replacement would remove the link itself.
+          const entry = await lstat(path).catch((error: unknown) => {
+            if (isObject(error) && error.code === "ENOENT") return undefined;
+            throw error;
+          });
+          if (entry?.isSymbolicLink()) {
+            throw new Error(`Compaction settings are a symbolic link; edit its target directly at ${path}`);
+          }
+          await rename(temporary, path);
+        } finally {
+          await rm(temporary, { force: true });
+        }
+      });
+    },
+  };
+}

package/src/fallback.ts

@@ -0,0 +1,92 @@
+// Own configured fallback selection and Pi's native text summarization through the model registry.
+import { getSupportedThinkingLevels, type Api, type AssistantMessage, type Model, type ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { compact, SettingsManager, type ExtensionAPI, type ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { FallbackConfiguration } from "./fallback-settings.js";
+
+const REQUEST_TIMEOUT_MS = 300_000;
+
+interface FallbackModel {
+  readonly model: Model<Api>;
+  readonly thinkingLevel: ModelThinkingLevel;
+}
+
+export interface FallbackCompactionRequest {
+  readonly configuration: FallbackConfiguration | undefined;
+  readonly modelRegistry: ModelRegistry;
+  readonly preparation: Parameters<typeof compact>[0];
+  readonly settings: ReturnType<ExtensionAPI["getSettings"]>;
+  readonly customInstructions?: string;
+  readonly signal: AbortSignal;
+  readonly sessionId: string;
+  /** Check session ownership before preparation and each provider attempt. */
+  readonly onPrepared: (selection: FallbackModel) => void;
+}
+
+function selectFallback(fallback: FallbackConfiguration | undefined, registry: ModelRegistry): FallbackModel | undefined {
+  if (!fallback?.enabled || fallback.model === undefined) return undefined;
+  const model = registry.find(fallback.provider, fallback.model);
+  if (!model) throw new Error(`fallback.model must name a configured model: ${fallback.provider}/${fallback.model}`);
+  const supportedLevels = getSupportedThinkingLevels(model);
+  const thinkingLevel = supportedLevels.find((level) => level === fallback.thinkingLevel);
+  if (thinkingLevel === undefined) {
+    throw new Error(`fallback.thinkingLevel must be supported by ${model.provider}/${model.id}: ${supportedLevels.join(", ")}`);
+  }
+  return { model, thinkingLevel };
+}
+
+/** Return undefined when fallback is disabled or unconfigured. Failures must stop native compaction on the chat model. */
+export async function requestFallbackCompaction(request: FallbackCompactionRequest) {
+  request.signal.throwIfAborted();
+  const selection = selectFallback(request.configuration, request.modelRegistry);
+  request.signal.throwIfAborted();
+  if (!selection) return undefined;
+  request.onPrepared(selection);
+  const settings = SettingsManager.inMemory(request.settings);
+  const providerRetry = settings.getProviderRetrySettings();
+  // pi-virtual limits are display hints. Zero lets native compact use its reserve budget;
+  // streamSimple routes the original model and caps each request to the physical model's limit.
+  const budgetModel = selection.model.api === "pi-virtual" ? { ...selection.model, maxTokens: 0 } : selection.model;
+  // Pi 0.99.1 can append file lists to empty or provider-aborted summaries; inspect the actual completions.
+  const responses: Promise<AssistantMessage>[] = [];
+  const result = await compact(
+    request.preparation,
+    budgetModel,
+    undefined,
+    undefined,
+    request.customInstructions,
+    request.signal,
+    selection.thinkingLevel,
+    (_model, context, options) => {
+      const stream = request.modelRegistry.streamSimple(selection.model, context, {
+        ...options,
+        transport: settings.getTransport(),
+        thinkingBudgets: settings.getThinkingBudgets(),
+        websocketConnectTimeoutMs: settings.getWebSocketConnectTimeoutMs(),
+        timeoutMs: providerRetry.timeoutMs ?? REQUEST_TIMEOUT_MS,
+        maxRetries: providerRetry.maxRetries,
+        maxRetryDelayMs: providerRetry.maxRetryDelayMs,
+        onPayload: (payload) => {
+          request.onPrepared(selection);
+          return payload;
+        },
+      });
+      responses.push(stream.result());
+      return stream;
+    },
+    undefined,
+    settings.getRetrySettings(),
+    undefined,
+    request.sessionId,
+  );
+  request.signal.throwIfAborted();
+  request.onPrepared(selection);
+  for (const response of responses) {
+    const message = await response;
+    if (message.stopReason === "aborted") throw new Error("Fallback compaction was aborted by the provider");
+    // Pi owns retrying error responses; validate only completions it accepted.
+    if (message.stopReason !== "error" && !message.content.some((block) => block.type === "text" && block.text.trim())) {
+      throw new Error("Fallback compaction returned an empty summary");
+    }
+  }
+  return { compaction: result };
+}

package/src/history-groups.ts

@@ -0,0 +1,45 @@
+// Own Codex's history item groups and the marked-text matching that contextual fragments share.
+// Reference: openai/codex rust-v0.159.2, compact_remote_history.rs and context-fragments/src/fragment.rs.
+import type { JsonObject } from "./protocol.js";
+
+const RESIZE_NOTICE_MARKERS = ["<image_resize_notice>", "</image_resize_notice>"] as const;
+
+export interface HistoryGroup {
+  readonly source: JsonObject;
+  readonly notice?: JsonObject;
+}
+
+/** Rust str::trim uses Unicode White_Space; JS trim additionally removes the BOM. */
+export function trimWhiteSpace(text: string): string {
+  return text.replace(/^\p{White_Space}+|\p{White_Space}+$/gu, "");
+}
+
+/** Match Codex's ASCII case-insensitive start and end markers on already trimmed text. */
+export function matchesMarkedText(text: string, [open, close]: readonly [string, string]): boolean {
+  const asciiLower = (value: string) => value.replace(/[A-Z]/g, (letter) => letter.toLowerCase());
+  return asciiLower(text.slice(0, open.length)) === asciiLower(open) &&
+    asciiLower(text.slice(-close.length)) === asciiLower(close);
+}
+
+/** Trimmed text of an input_text part, or undefined for any other part. */
+export function inputText(value: unknown): string | undefined {
+  return typeof value === "object" && value !== null && "type" in value && value.type === "input_text" &&
+    "text" in value && typeof value.text === "string" ? trimWhiteSpace(value.text) : undefined;
+}
+
+function isResizeNotice(item: JsonObject): boolean {
+  if ((item.type !== undefined && item.type !== "message") || item.role !== "developer" ||
+    !Array.isArray(item.content) || item.content.length !== 1) return false;
+  const text = inputText(item.content[0]);
+  return text !== undefined && matchesMarkedText(text, RESIZE_NOTICE_MARKERS);
+}
+
+/** Group each item with an immediately following resize notice, as Codex's history_item_groups does. */
+export function historyGroups(input: readonly JsonObject[]): HistoryGroup[] {
+  const groups: HistoryGroup[] = [];
+  for (let index = 0; index < input.length; index++) {
+    const next = input[index + 1];
+    groups.push({ source: input[index], notice: next && isResizeNotice(next) ? input[++index] : undefined });
+  }
+  return groups;
+}