@criogaid/pi-codex-compaction 0.3.0

package/src/image-budget.ts

@@ -0,0 +1,93 @@
+// Own Codex image byte estimates and the adapter to Pi's image decoder.
+// Decode serially; cancellation is checked between decodes because Pi exposes no decode abort hook.
+import { createHash } from "node:crypto";
+import { resizeImage } from "@earendil-works/pi-coding-agent";
+import { isInputImage, type JsonObject } from "./protocol.js";
+import { approximateBytesForTokens } from "./text-budget.js";
+
+export const RESIZED_IMAGE_BYTES_ESTIMATE = 7_373;
+const ORIGINAL_IMAGE_PATCH_SIZE_PX = 32;
+const ORIGINAL_IMAGE_MAX_PATCHES = 10_000;
+const ORIGINAL_IMAGE_ESTIMATE_CACHE_SIZE = 32;
+const DIMENSION_PROBE_LIMIT = Number.MAX_SAFE_INTEGER;
+
+/** Byte estimates for input images; original-detail inline images are decoded ahead of lookup. */
+export interface ImageEstimates {
+  bytes(part: JsonObject): number;
+}
+
+async function inlineOriginalBytes(url: string): Promise<number | undefined> {
+  const comma = url.indexOf(",");
+  if (comma < 0 || !/^data:image\//i.test(url)) return undefined;
+  const [mimeType, ...parameters] = url.slice("data:".length, comma).split(";");
+  if (!parameters.some((parameter) => parameter.toLowerCase() === "base64")) return undefined;
+  const payload = url.slice(comma + 1);
+  const bytes = Buffer.from(payload, "base64");
+  // Rust's standard base64 decoder rejects noncanonical padding and trailing bits.
+  if (bytes.toString("base64") !== payload) return undefined;
+  const decoded = await resizeImage(bytes, mimeType, {
+    maxWidth: DIMENSION_PROBE_LIMIT, maxHeight: DIMENSION_PROBE_LIMIT, maxBytes: DIMENSION_PROBE_LIMIT,
+  });
+  if (!decoded) return undefined;
+  return approximateBytesForTokens(Math.min(ORIGINAL_IMAGE_MAX_PATCHES,
+    Math.ceil(decoded.originalWidth / ORIGINAL_IMAGE_PATCH_SIZE_PX) *
+    Math.ceil(decoded.originalHeight / ORIGINAL_IMAGE_PATCH_SIZE_PX)));
+}
+
+// Like Codex, cache decode results, including failures, across requests in a SHA-1 keyed LRU.
+const originalEstimateCache = new Map<string, number | undefined>();
+
+async function cachedOriginalBytes(url: string): Promise<number | undefined> {
+  const key = createHash("sha1").update(url).digest("hex");
+  if (originalEstimateCache.has(key)) {
+    const cached = originalEstimateCache.get(key);
+    originalEstimateCache.delete(key);
+    originalEstimateCache.set(key, cached);
+    return cached;
+  }
+  const bytes = await inlineOriginalBytes(url);
+  originalEstimateCache.set(key, bytes);
+  if (originalEstimateCache.size > ORIGINAL_IMAGE_ESTIMATE_CACHE_SIZE) {
+    const oldest = originalEstimateCache.keys().next().value;
+    if (oldest !== undefined) originalEstimateCache.delete(oldest);
+  }
+  return bytes;
+}
+
+function contentParts(item: JsonObject): readonly unknown[] {
+  if (Array.isArray(item.content)) return item.content;
+  return (item.type === "function_call_output" || item.type === "custom_tool_call_output") &&
+    Array.isArray(item.output) ? item.output : [];
+}
+
+function originalInlineUrl(part: JsonObject): string | undefined {
+  return part.detail === "original" && typeof part.file_id !== "string" && typeof part.image_url === "string"
+    ? part.image_url : undefined;
+}
+
+/** Decode original-detail inline images in message content and tool outputs; lookups survive cloning. */
+export async function estimateImages(input: readonly JsonObject[], signal: AbortSignal): Promise<ImageEstimates> {
+  const originals = new Map<string, number>();
+  for (const item of input) {
+    for (const part of contentParts(item)) {
+      signal.throwIfAborted();
+      if (!isInputImage(part)) continue;
+      const url = originalInlineUrl(part);
+      if (url === undefined || originals.has(url)) continue;
+      originals.set(url, await cachedOriginalBytes(url) ?? RESIZED_IMAGE_BYTES_ESTIMATE);
+    }
+  }
+  signal.throwIfAborted();
+  return {
+    bytes(part) {
+      if (part.detail === "original" && typeof part.file_id === "string") {
+        return approximateBytesForTokens(ORIGINAL_IMAGE_MAX_PATCHES);
+      }
+      const url = originalInlineUrl(part);
+      if (url === undefined) return RESIZED_IMAGE_BYTES_ESTIMATE;
+      const bytes = originals.get(url);
+      if (bytes === undefined) throw new Error("Input image is missing its byte estimate");
+      return bytes;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,370 @@
+// Own Pi lifecycle integration, active-session ownership, checkpoint replay hooks, and compaction orchestration.
+import { resolve } from "node:path";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { Tool } from "@earendil-works/pi-ai";
+import {
+  buildSessionContext,
+  getAgentDir,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type SessionBeforeCompactEvent,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { prepareRetention, userItemOrigins } from "./retention-input.js";
+import { buildReplacementHistory } from "./retention.js";
+import {
+  capableModel,
+  sameBackend,
+  sameProvider,
+  type CapableModel,
+  type ProviderIdentity,
+} from "./capability.js";
+import {
+  type CodexCheckpointDetails,
+  checkpointMarker,
+  createCheckpointDetails,
+  fallbackSummary,
+  keptMessages,
+  latestCheckpoint,
+  parseCheckpointDetails,
+  projectCheckpointContext,
+  projectCheckpointRequest,
+} from "./checkpoint.js";
+import { hasCheckpointMarker, type JsonObject, REMOTE_COMPACTION_PROTOCOL, rewriteCheckpointMarker } from "./protocol.js";
+import { requestRemoteCompaction } from "./remote.js";
+import { requestFallbackCompaction } from "./fallback.js";
+import { COMPACTION_SETTINGS_RELATIVE_PATH, loadCompactionSettings, type CompactionConfiguration } from "./fallback-settings.js";
+import { registerCompactionCommand } from "./fallback-command.js";
+import { compactionRequest, RequestSnapshotTracker, type RequestSnapshots } from "./request-snapshot.js";
+
+const STATUS_KEY = "codex-compaction";
+const COMPLETION_ENTRY_TYPE = "pi-codex-compaction-completed";
+
+interface CompletionEntryData {
+  message: string;
+  protocol: typeof REMOTE_COMPACTION_PROTOCOL;
+  checkpointId: string;
+}
+
+function activeCheckpoint(ctx: ExtensionContext) {
+  return latestCheckpoint(ctx.sessionManager.getBranch());
+}
+
+async function compatibleIdentity(
+  details: CodexCheckpointDetails,
+  ctx: ExtensionContext,
+  model = ctx.model,
+): Promise<CapableModel | undefined> {
+  if (!model || !sameProvider(details, model)) return undefined;
+  // Resolve only endpoint identity here; Pi still owns authorization and request dispatch.
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok) return undefined;
+  const supported = capableModel(model, auth.baseUrl);
+  return supported && sameBackend(details, supported.identity) ? supported : undefined;
+}
+
+function activeTools(pi: ExtensionAPI): Tool[] {
+  const enabled = new Set(pi.getActiveTools());
+  return pi
+    .getAllTools()
+    .filter((tool) => enabled.has(tool.name))
+    .map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    }));
+}
+
+function canonicalMessages(ctx: ExtensionContext): AgentMessage[] {
+  const branch = ctx.sessionManager.getBranch();
+  return buildSessionContext(branch, branch.at(-1)?.id ?? null).messages;
+}
+
+function projectedCurrentMessages(
+  event: SessionBeforeCompactEvent,
+  identity: ProviderIdentity,
+): { messages: AgentMessage[]; prior?: CodexCheckpointDetails } {
+  const leafId = event.branchEntries.at(-1)?.id ?? null;
+  const session = buildSessionContext(event.branchEntries, leafId);
+  const prior = latestCheckpoint(event.branchEntries)?.details;
+  if (!prior) return { messages: session.messages };
+  if (!sameProvider(prior, identity)) {
+    throw new Error("The active opaque checkpoint belongs to a different provider backend");
+  }
+  const projected = projectCheckpointRequest(session.messages, prior);
+  if (!projected) throw new Error("The previous opaque checkpoint could not be projected safely");
+  return { messages: projected, prior };
+}
+
+async function replayCheckpoint(payload: unknown, ctx: ExtensionContext): Promise<JsonObject | undefined> {
+  const checkpoint = activeCheckpoint(ctx);
+  if (!checkpoint) return undefined;
+  const marker = checkpointMarker(checkpoint.details.checkpointId);
+  if (!hasCheckpointMarker(payload, marker)) return undefined;
+  if (!await compatibleIdentity(checkpoint.details, ctx)) {
+    throw new Error("The active opaque checkpoint no longer matches the resolved provider endpoint");
+  }
+  return rewriteCheckpointMarker(payload, marker, checkpoint.details.replacementHistory);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function notifyFailure(ctx: ExtensionContext, error: unknown): void {
+  if (!ctx.hasUI) return;
+  ctx.ui.notify(`Codex remote compaction failed; using Pi compaction. ${errorMessage(error)}`, "warning");
+}
+
+function sessionStillOwned(ctx: ExtensionContext, sessionId: string, signal: AbortSignal): boolean {
+  return !signal.aborted && ctx.sessionManager.getSessionId() === sessionId;
+}
+
+async function compactFallback(
+  pi: ExtensionAPI,
+  event: SessionBeforeCompactEvent,
+  ctx: ExtensionContext,
+  sessionId: string,
+  configuration: CompactionConfiguration,
+  remoteError?: unknown,
+) {
+  let announced = false;
+  try {
+    if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+    const result = await requestFallbackCompaction({
+      configuration: configuration.fallback,
+      modelRegistry: ctx.modelRegistry,
+      preparation: event.preparation,
+      settings: pi.getSettings(),
+      customInstructions: event.customInstructions,
+      signal: event.signal,
+      sessionId,
+      onPrepared: ({ model, thinkingLevel }) => {
+        if (!sessionStillOwned(ctx, sessionId, event.signal)) throw new Error("Compaction session ownership changed");
+        if (announced) return;
+        announced = true;
+        ctx.ui.setStatus(STATUS_KEY, "Pi fallback compaction...");
+        if (ctx.hasUI) {
+          if (remoteError !== undefined) {
+            ctx.ui.notify(`Codex remote compaction failed; using the configured fallback model. ${errorMessage(remoteError)}`, "warning");
+          }
+          ctx.ui.notify(`Using Pi text compaction with ${model.provider}/${model.id} (${thinkingLevel}).`, "info");
+        }
+      },
+    });
+    if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+    if (!result && remoteError !== undefined) notifyFailure(ctx, remoteError);
+    return result;
+  } catch (error) {
+    if (sessionStillOwned(ctx, sessionId, event.signal) && ctx.hasUI) {
+      ctx.ui.notify(`Configured fallback compaction failed; compaction stopped. ${errorMessage(error)}`, "error");
+    }
+    // Returning undefined would make Pi send the same context to the active chat model.
+    return { cancel: true };
+  } finally {
+    if (ctx.sessionManager.getSessionId() === sessionId) ctx.ui.setStatus(STATUS_KEY, undefined);
+  }
+}
+
+async function compactRemotely(
+  pi: ExtensionAPI,
+  event: SessionBeforeCompactEvent,
+  ctx: ExtensionContext,
+  compactionSettingsPath: string,
+  fetch?: typeof globalThis.fetch,
+  snapshots: RequestSnapshots = {},
+) {
+  const supported = capableModel(ctx.model);
+  const sessionId = ctx.sessionManager.getSessionId();
+  if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+  let configuration: CompactionConfiguration;
+  try {
+    configuration = (await loadCompactionSettings(compactionSettingsPath)).configuration;
+  } catch (error) {
+    if (sessionStillOwned(ctx, sessionId, event.signal) && ctx.hasUI) {
+      ctx.ui.notify(`Could not read compaction settings; compaction stopped. ${errorMessage(error)}`, "error");
+    }
+    return { cancel: true };
+  }
+  if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+  if (!configuration.remoteCompactionEnabled || !supported) return compactFallback(pi, event, ctx, sessionId, configuration);
+  const reasoning = pi.getThinkingLevel();
+  const settings = pi.getSettings();
+  let announced = false;
+  ctx.ui.setStatus(STATUS_KEY, "Codex remote compaction...");
+  try {
+    if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+    if (event.customInstructions?.trim() && ctx.hasUI) {
+      ctx.ui.notify("Codex Remote Compaction V2 does not accept custom instructions; they are ignored.", "warning");
+    }
+    const current = projectedCurrentMessages(event, supported.identity);
+    const request = compactionRequest(snapshots, sessionId, supported, current.messages, {
+      blockImages: settings.images?.blockImages ?? false,
+      systemPrompt: () => ctx.getSystemPrompt(),
+      tools: () => activeTools(pi),
+    });
+    const response = await requestRemoteCompaction({
+      modelRegistry: ctx.modelRegistry,
+      model: supported.model,
+      context: request.context,
+      userItemOrigins: userItemOrigins(request.messages),
+      reasoning,
+      sessionId,
+      thinkingBudgets: settings.thinkingBudgets,
+      maxRetries: settings.retry?.provider?.maxRetries,
+      maxRetryDelayMs: settings.retry?.provider?.maxRetryDelayMs,
+      signal: event.signal,
+      onPrepared: () => {
+        if (!sessionStillOwned(ctx, sessionId, event.signal)) throw new Error("Compaction session ownership changed");
+        // Provider retries prepare the payload again; announce the compaction once.
+        if (announced) return;
+        announced = true;
+        if (ctx.hasUI) ctx.ui.notify(
+          `Starting Codex Remote Compaction V2 for ${supported.identity.provider}/${supported.identity.modelId}.`,
+          "info",
+        );
+      },
+      priorCheckpoint: current.prior
+        ? {
+            identity: current.prior,
+            marker: checkpointMarker(current.prior.checkpointId),
+            replacementHistory: current.prior.replacementHistory,
+          }
+        : undefined,
+      fetch,
+    });
+    if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+    const retention = await prepareRetention(response.promptInput, event.signal, {
+      images: response.images,
+      contextual: response.contextual,
+    });
+    if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+    const replacementHistory = buildReplacementHistory(retention, response.item);
+    const details = createCheckpointDetails({
+      identity: response.identity,
+      replacementHistory,
+      keptMessages: keptMessages(event.branchEntries, event.preparation.firstKeptEntryId),
+    });
+    return {
+      compaction: {
+        summary: fallbackSummary(details.checkpointId),
+        firstKeptEntryId: event.preparation.firstKeptEntryId,
+        tokensBefore: event.preparation.tokensBefore,
+        usage: response.usage,
+        details,
+      },
+    };
+  } catch (error) {
+    if (event.signal.aborted || ctx.sessionManager.getSessionId() !== sessionId) {
+      return { cancel: true };
+    }
+    return await compactFallback(pi, event, ctx, sessionId, configuration, error);
+  } finally {
+    if (ctx.sessionManager.getSessionId() === sessionId) {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+    }
+  }
+}
+
+export function createCodexCompactionExtension(
+  options: { fetch?: typeof globalThis.fetch } = {},
+): (pi: ExtensionAPI) => void {
+  return (pi) => {
+    const compactionSettingsPath = resolve(getAgentDir(), COMPACTION_SETTINGS_RELATIVE_PATH);
+    registerCompactionCommand(pi, compactionSettingsPath);
+    const warnings = new Set<string>();
+    const snapshots = new RequestSnapshotTracker();
+
+    pi.registerEntryRenderer<CompletionEntryData>(
+      COMPLETION_ENTRY_TYPE,
+      (entry, _options, theme) => {
+        const message = entry.data?.message;
+        return typeof message === "string"
+          ? new Text(theme.fg("success", message), 1, 0)
+          : undefined;
+      },
+    );
+
+    pi.on("session_start", () => {
+      warnings.clear();
+      snapshots.reset();
+    });
+
+    pi.on("session_before_compact", (event, ctx) =>
+      compactRemotely(pi, event, ctx, compactionSettingsPath, options.fetch, snapshots.current()),
+    );
+
+    pi.on("session_compact", (event) => {
+      if (!event.fromExtension) return;
+      const details = parseCheckpointDetails(event.compactionEntry.details);
+      if (!details) return;
+      pi.appendEntry<CompletionEntryData>(COMPLETION_ENTRY_TYPE, {
+        message: `Codex Remote Compaction V2 completed for ${details.provider}/${details.modelId}.`,
+        protocol: REMOTE_COMPACTION_PROTOCOL,
+        checkpointId: details.checkpointId,
+      });
+    });
+
+    pi.on("context", async (event, ctx) => {
+      snapshots.recordContext(ctx.sessionManager.getSessionId(), capableModel(ctx.model), event.messages);
+      const checkpoint = activeCheckpoint(ctx);
+      if (!checkpoint || !await compatibleIdentity(checkpoint.details, ctx)) return undefined;
+      const messages = projectCheckpointContext(event.messages, checkpoint.details);
+      if (messages) return { messages };
+      const key = `${ctx.sessionManager.getSessionId()}:${checkpoint.details.checkpointId}:projection`;
+      if (!warnings.has(key)) {
+        warnings.add(key);
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            "The active Codex checkpoint no longer matches the retained messages, so its opaque history is not replayed.",
+            "warning",
+          );
+        }
+      }
+      return undefined;
+    });
+
+    pi.on("context_with_system", (event, ctx) => {
+      snapshots.recordProjectedRequest(
+        ctx.sessionManager.getSessionId(),
+        capableModel(ctx.model),
+        () => canonicalMessages(ctx),
+        () => activeCheckpoint(ctx)?.details,
+        event.messages,
+      );
+    });
+
+    pi.on("before_provider_request", async (event, ctx) => {
+      const payload = await replayCheckpoint(event.payload, ctx);
+      snapshots.recordProviderRequest(
+        ctx.sessionManager.getSessionId(),
+        capableModel(ctx.model),
+        () => canonicalMessages(ctx),
+        () => ctx.getSystemPrompt(),
+      );
+      return payload;
+    });
+
+    pi.on("model_select", async (event, ctx) => {
+      const checkpoint = activeCheckpoint(ctx);
+      if (!checkpoint || await compatibleIdentity(checkpoint.details, ctx, event.model)) return;
+      const key = `${ctx.sessionManager.getSessionId()}:${event.model.provider}:${event.model.id}`;
+      if (warnings.has(key)) return;
+      warnings.add(key);
+      if (ctx.hasUI) {
+        ctx.ui.notify(
+          "The active Codex checkpoint cannot replay on this provider backend; only its fallback marker and retained recent messages remain available.",
+          "warning",
+        );
+      }
+    });
+
+    pi.on("session_shutdown", (_event, ctx) => {
+      warnings.clear();
+      snapshots.reset();
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+    });
+  };
+}
+
+export default createCodexCompactionExtension();

package/src/protocol.ts

@@ -0,0 +1,155 @@
+// Own Responses V2 item validation and checkpoint payload transformations.
+export const REMOTE_COMPACTION_PROTOCOL = "remote-compaction-v2" as const;
+
+export type JsonObject = Record<string, unknown>;
+
+export class CodexCompactionProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CodexCompactionProtocolError";
+  }
+}
+
+export function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isInputImage(value: unknown): value is JsonObject {
+  return isObject(value) && value.type === "input_image";
+}
+
+function isCompactionType(type: unknown): boolean {
+  return type === "compaction" || type === "compaction_summary";
+}
+
+export function validateCompactionItem(
+  value: unknown,
+): JsonObject {
+  if (
+    !isObject(value) ||
+    !isCompactionType(value.type) ||
+    typeof value.encrypted_content !== "string" ||
+    !value.encrypted_content
+  ) {
+    throw new CodexCompactionProtocolError(
+      "Remote response did not contain a valid compaction item",
+    );
+  }
+  return { ...structuredClone(value), type: "compaction" };
+}
+
+export interface CompactionCollector {
+  observe(event: unknown): void;
+  finish(): JsonObject;
+}
+
+/** Count output-item completion events, as Codex does; response.output is not another source. */
+export function createCompactionCollector(): CompactionCollector {
+  let count = 0;
+  let item: JsonObject | undefined;
+  let completed = false;
+  return {
+    observe(event) {
+      if (!isObject(event)) return;
+      // A provider may restart its response when falling back from WebSocket to HTTP.
+      if (event.type === "response.created") {
+        count = 0;
+        item = undefined;
+        completed = false;
+      }
+      if (event.type === "response.output_item.done" && isObject(event.item) &&
+          isCompactionType(event.item.type)) {
+        count += 1;
+        item = validateCompactionItem(event.item);
+      }
+      if (event.type === "response.completed") completed = true;
+    },
+    finish() {
+      if (!completed) {
+        throw new CodexCompactionProtocolError(
+          "Remote compaction stream ended without response.completed",
+        );
+      }
+      if (count !== 1 || !item) {
+        throw new CodexCompactionProtocolError(
+          `Remote compaction returned ${count} compaction output events; expected exactly one`,
+        );
+      }
+      return item;
+    },
+  };
+}
+
+function markerText(item: unknown): string | undefined {
+  if (
+    !isObject(item) ||
+    item.role !== "user" ||
+    !Array.isArray(item.content) ||
+    item.content.length !== 1
+  ) {
+    return undefined;
+  }
+  const content = item.content[0];
+  return isObject(content) &&
+    content.type === "input_text" &&
+    typeof content.text === "string"
+    ? content.text
+    : undefined;
+}
+
+export function rewriteCheckpointMarker(
+  payload: unknown,
+  marker: string,
+  replacementHistory: readonly unknown[],
+): JsonObject {
+  if (!isObject(payload) || !Array.isArray(payload.input)) {
+    throw new CodexCompactionProtocolError("Codex payload is missing an input array");
+  }
+  const matches = payload.input
+    .map((item, index) => (markerText(item) === marker ? index : -1))
+    .filter((index) => index >= 0);
+  if (matches.length !== 1) {
+    throw new CodexCompactionProtocolError(
+      `Provider payload contained ${matches.length} checkpoint markers; expected exactly one`,
+    );
+  }
+  const index = matches[0];
+  return {
+    ...payload,
+    input: [
+      ...payload.input.slice(0, index),
+      ...structuredClone(replacementHistory),
+      ...payload.input.slice(index + 1),
+    ],
+  };
+}
+
+export function appendCompactionTrigger(payload: unknown): JsonObject {
+  if (!isObject(payload) || !Array.isArray(payload.input)) {
+    throw new CodexCompactionProtocolError("Codex payload is missing an input array");
+  }
+  if (payload.input.some((item) => isObject(item) && item.type === "compaction_trigger")) {
+    throw new CodexCompactionProtocolError("Provider payload already contains a compaction trigger");
+  }
+  return { ...payload, input: [...payload.input, { type: "compaction_trigger" }] };
+}
+
+/** Replay the checkpoint, let the caller adapt the history, then append the V2 trigger. */
+export function prepareRemoteCompactionPayload(
+  payload: unknown,
+  checkpoint?: { marker: string; replacementHistory: readonly unknown[] },
+  adaptHistory?: (history: JsonObject) => JsonObject,
+): JsonObject {
+  const history = checkpoint
+    ? rewriteCheckpointMarker(payload, checkpoint.marker, checkpoint.replacementHistory)
+    : payload;
+  return appendCompactionTrigger(adaptHistory && isObject(history) ? adaptHistory(history) : history);
+}
+
+export function hasCheckpointMarker(payload: unknown, marker: string): boolean {
+  return (
+    isObject(payload) &&
+    Array.isArray(payload.input) &&
+    payload.input.some((item) => markerText(item) === marker)
+  );
+}