pi-openai-toolkit 0.6.0 → 0.7.1

package/README.md

@@ -1,7 +1,7 @@
 # pi-openai-toolkit
 
 <p align="center">
-  <strong>OpenAI-focused toolkit for <a href="https://github.com/badlogic/pi">Pi</a>: Native Remote Compaction v2 & Hosted Web Search</strong>
+  <strong>OpenAI-focused toolkit for <a href="https://github.com/earendil-works/pi">Pi</a>: Native Remote Compaction v2 & Hosted Web Search</strong>
 </p>
 
 <p align="center">
@@ -87,6 +87,11 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "remoteCompactModel": "uwoacrimson/gpt-5.6-luna",
     "model": null,
     "thinkingLevel": "off",
+    "autoCompaction": {
+      "enabled": true,
+      "continuation": "inline",
+      "unsupportedFallback": "followUp"
+    },
     "responsesApis": [
       "openai-responses",
       "openai-codex-responses"
@@ -113,9 +118,13 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 
 - `enabled` (*boolean*, default: `true`): Enable or disable Remote Compaction.
 - `allowCompactionContinuityBreak` (*boolean*, default: `false`): When `true`, allows restarting a fresh native opaque compaction chain from Pi's current session text if the latest compaction was made by another strategy (e.g. text summary).
-- `remoteCompactModel` (*string | null*, default: `null`): Model formatted as `provider/model-id` used only for the synthetic `remote_compaction_v2` request. Pi's active session model is not switched and resumes normal requests after compaction. The override must resolve to the same provider, Responses API identifier, and effective base URL as the active model. `null` preserves the current same-model path.
+- `remoteCompactModel` (*string | null*, default: `null`): Model formatted as `provider/model-id` used only for the synthetic `remote_compaction_v2` request. Pi's active session model is not switched and resumes normal requests after compaction. The override must resolve to the same effective base URL as the active model; provider, Responses API identifier, and model may differ. `null` preserves the current same-model path.
 - `model` (*string | null*, default: `null`): Separate native text-summary fallback model formatted as `provider/model-id` (e.g. `"openai/gpt-4o-mini"`) used if remote v2 is unavailable or fails. If `null`, Pi uses its default current-model compaction path.
 - `thinkingLevel` (*string*, default: `"off"`): Reasoning / thinking level passed to Pi native compaction fallback (`"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`).
+- `autoCompaction.enabled` (*boolean*, default: `true`): Check for compaction after a completed tool-result batch crosses Pi's context threshold.
+- `autoCompaction.continuation` (*`"inline" | "followUp" | "off"`*, default: `"inline"`): `inline` compacts inside the current official Pi 0.84.3 tool loop and refreshes the next provider context; `followUp` uses Pi's public hidden follow-up message path; `off` disables toolkit-triggered automatic compaction.
+- `autoCompaction.unsupportedFallback` (*`"followUp" | "off"`*, default: `"followUp"`): Behavior when the guarded official-host inline adapter is unavailable. It does not change normal remote/native compaction fallback ordering.
+- `autoCompaction.reserveTokens` (*non-negative integer*, optional): Override only the automatic trigger reserve. When omitted, the active Pi compaction setting is used. Pi's `keepRecentTokens` remains authoritative for compactability.
 - `responsesApis` (*string[]*): Narrow the supported remote compaction API identifiers (subset of `["openai-responses", "openai-codex-responses"]`).
 - `notifyOnLoad` (*boolean*, default: `false`): Show a notification banner on Pi startup.
 - `debug` (*boolean*, default: `false`): Output diagnostics and write execution artifacts to disk.
@@ -154,12 +163,22 @@ Content-Type: application/json
 - **Validation Criteria**: Must return a valid SSE stream with `response.completed` (status `completed`) containing exactly one output item of `type: "compaction"` with non-empty `encrypted_content`.
 - **Remote Model Override**: `compaction.remoteCompactModel` can assign a same-gateway Responses model as the checkpoint producer while the active model remains the consumer. Its registered model metadata, authentication, headers, and effective base URL are used only for the synthetic compact request. Existing and recursive checkpoints remain replayable by the active model.
 - **Zero Loss Replay**: The opaque encrypted item is stored in `CompactionEntry.details.compactedWindow`. On subsequent requests, it is transparently prepended after fresh preamble instructions alongside live turns, eliminating lossy text re-summaries.
+- **Fail-Closed Replay Guard**: Replay verifies only the compaction summary sentinel plus the kept pre-compaction window derived from session entries; leading/trailing prompts and the post-compaction live tail are preserved verbatim, so transient messages injected by other extensions no longer block replay. If the kept region cannot be verified (e.g. `expected-pi-replay-mismatch` or `compaction-summary-not-found`), the toolkit aborts the provider request, shows an error notification, and always writes a content-free `*-replay-failure.json` artifact even when `logProviderPayloads` is disabled. The sentinel-only payload is never sent to the model.
 - **Graceful Multi-Tier Fallback**:
   1. Compatible Responses endpoints &rarr; Remote v2 Opaque Compaction.
   2. Gateway failure or non-Responses model &rarr; Configured `compaction.model` fallback.
   3. Otherwise &rarr; Pi default native text compaction.
 
-### 2. Model-Scoped Web Search
+### 2. Tool-Loop Auto-Compaction and Continuation
+
+After every complete tool-call/result batch, the toolkit checks the current Pi usage threshold. It then mirrors official Pi's `prepareCompaction()` eligibility using Pi's exported cut-point and session-entry helpers before invoking the normal `AgentSession.compact()` path.
+
+- **Inline mode**: On the guarded official Pi `0.84.3` host shape, compaction finishes before the next provider request and `prepareNextTurnWithContext` receives the newly built Pi session context. Remote v2, native fallback, replay rewriting, hook order, and deferred-tool carryover still run through their existing owners.
+- **Too-small sessions**: Crossing the token threshold does not prove there is discardable history. If Pi has nothing to summarize, the toolkit does not call `compact()`, does not abort the active run, and lets the unfinished tool loop continue normally.
+- **Public fallback**: `followUp` uses `ExtensionAPI.sendMessage` with a hidden `followUp` message after compaction. The turn is handled once, preventing repeated compaction/follow-up storms.
+- **Version guard**: The private same-loop adapter is enabled only for the structurally verified official Pi `0.84.3` `AgentSession`. Unsupported hosts use the configured public fallback or disable automatic continuation.
+
+### 3. Model-Scoped Web Search
 
 For allowlisted models using `openai-responses` or `openai-codex-responses`, the extension hooks into `before_provider_request` and `before_agent_start`:
 

package/README_zh.md

@@ -1,7 +1,7 @@
 # pi-openai-toolkit
 
 <p align="center">
-  <strong>专为 <a href="https://github.com/badlogic/pi">Pi</a> 打造的 OpenAI 全功能增强工具包：远端无损压缩 v2 & 原生托管联网搜索</strong>
+  <strong>专为 <a href="https://github.com/earendil-works/pi">Pi</a> 打造的 OpenAI 全功能增强工具包：远端无损压缩 v2 & 原生托管联网搜索</strong>
 </p>
 
 <p align="center">
@@ -87,6 +87,11 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
     "remoteCompactModel": "uwoacrimson/gpt-5.6-luna",
     "model": null,
     "thinkingLevel": "off",
+    "autoCompaction": {
+      "enabled": true,
+      "continuation": "inline",
+      "unsupportedFallback": "followUp"
+    },
     "responsesApis": [
       "openai-responses",
       "openai-codex-responses"
@@ -113,9 +118,13 @@ C:\Users\<user>\.pi\agent\extensions\pi-openai-toolkit\config.json
 
 - `enabled` (*boolean*, 默认 `true`): 是否启用远端无损压缩。
 - `allowCompactionContinuityBreak` (*boolean*, 默认 `false`): 若最近一次历史压缩由其他方式（如文本摘要）生成，设为 `true` 允许直接从当前有效文本上下文重建密文压缩链。
-- `remoteCompactModel` (*string | null*, 默认 `null`): 仅用于 synthetic `remote_compaction_v2` 请求的模型，格式为 `"provider/model-id"`。Pi 不会切换当前会话模型，压缩完成后仍由原模型继续正常请求。覆盖模型必须与当前模型使用相同的 Provider、Responses API 标识符和实际生效的 Base URL。为 `null` 时保持当前模型执行远端压缩的原有行为。
+- `remoteCompactModel` (*string | null*, 默认 `null`): 仅用于 synthetic `remote_compaction_v2` 请求的模型，格式为 `"provider/model-id"`。Pi 不会切换当前会话模型，压缩完成后仍由原模型继续正常请求。覆盖模型必须与当前模型使用相同的实际生效 Base URL；Provider、Responses API 标识符和模型本身可以不同。为 `null` 时保持当前模型执行远端压缩的原有行为。
 - `model` (*string | null*, 默认 `null`): 独立的原生文本摘要降级模型，格式为 `"provider/model-id"`（例如 `"openai/gpt-4o-mini"`）。当 Remote v2 不可用或失败时使用；为 `null` 时进入 Pi 默认的当前模型压缩路径。
 - `thinkingLevel` (*string*, 默认 `"off"`): 降级模型调用 Pi 原生压缩时的思考级别（`"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`）。
+- `autoCompaction.enabled` (*boolean*, 默认 `true`): 完整工具调用/结果批次结束并越过 Pi 上下文阈值后，检查是否需要压缩。
+- `autoCompaction.continuation` (*`"inline" | "followUp" | "off"`*, 默认 `"inline"`): `inline` 在官方 Pi 0.84.3 当前工具循环内完成压缩并刷新下一次 Provider 上下文；`followUp` 使用 Pi 公共的隐藏后续消息；`off` 关闭 Toolkit 触发的自动压缩。
+- `autoCompaction.unsupportedFallback` (*`"followUp" | "off"`*, 默认 `"followUp"`): 官方 Host 私有 inline 适配器不可用时的处理方式，不改变原有远端/原生压缩降级顺序。
+- `autoCompaction.reserveTokens` (*非负整数*, 可选): 仅覆盖自动触发阈值的保留 Token 数。未设置时使用当前 Pi 压缩配置；是否具有可压缩历史仍以 Pi 的 `keepRecentTokens` 为准。
 - `responsesApis` (*string[]*): 允许尝试远端压缩的 API 标识符子集（从 `["openai-responses", "openai-codex-responses"]` 中选定）。
 - `notifyOnLoad` (*boolean*, 默认 `false`): Pi 启动加载时是否弹出气泡提示。
 - `debug` (*boolean*, 默认 `false`): 是否开启调试模式并记录诊断日志。
@@ -154,12 +163,22 @@ Content-Type: application/json
 - **校验标准**：接收 SSE 流并验证 `response.completed` 事件（状态为 `completed`），且返回且仅返回一个包含非空 `encrypted_content` 密文的 `type: "compaction"` 数据块。
 - **远端压缩模型覆盖**：`compaction.remoteCompactModel` 可以让同一网关上的另一个 Responses 模型负责生成 checkpoint，而当前活动模型仍是 checkpoint 的消费者。synthetic 压缩请求会使用覆盖模型在注册表中的模型元数据、认证、请求头和实际 Base URL；旧 checkpoint、递归压缩 checkpoint 都仍由当前活动模型重放。
 - **无损重放机制**：密文数据完整存入 `CompactionEntry.details.compactedWindow`。在后续对话中，插件会自动将密文插入在最新的系统指令之后与最新几轮消息之前，实现完全服务端无损上下文还原。
+- **重放失败保护（Fail-Closed）**：重放只校验 compaction summary 哨兵项以及由 session entries 推导出的压缩前保留窗口；前置/后置 prompt 与压缩后的实时尾部消息一律原样保留，因此其他扩展注入的临时消息不再阻断重放。若保留窗口无法与 session entries 对齐（如 `expected-pi-replay-mismatch`、`compaction-summary-not-found`），插件会中止 provider 请求、弹出错误通知，并且即使 `logProviderPayloads` 关闭也会写入一份不含内容的安全失败记录 `*-replay-failure.json`。只含哨兵占位符的请求体永远不会发送给模型。
 - **三级优雅降级**：
   1. 支持的 Responses 端点 &rarr; 触发 Remote v2 密文无损压缩；
   2. 网关不支持或报错 &rarr; 降级调用用户指定的 `compaction.model`；
   3. 未配置降级模型 &rarr; 回退至 Pi 默认的当前模型摘要压缩。
 
-### 2. 按模型启用的联网搜索
+### 2. 工具循环内自动压缩与续跑
+
+每个完整工具调用/结果批次结束后，Toolkit 会检查当前 Pi 上下文阈值。真正调用压缩前，它使用 Pi 导出的 cut-point 与 session-entry helper 复现官方 `prepareCompaction()` 的可压缩性门禁，然后仍通过正常的 `AgentSession.compact()` 路径执行。
+
+- **Inline 模式**：仅在结构校验通过的官方 Pi `0.84.3` Host 上启用。压缩会在下一次 Provider 请求前完成，`prepareNextTurnWithContext` 使用 Pi 重建后的最新会话上下文。Remote v2、原生降级、密文重放、Hook 顺序和 deferred-tool carryover 仍由原有实现负责。
+- **历史过短**：越过 Token 阈值不代表一定存在可丢弃历史。若 Pi 没有可摘要内容，Toolkit 不调用 `compact()`、不终止当前运行，让未完成的工具循环正常继续。
+- **公共降级**：`followUp` 通过 `ExtensionAPI.sendMessage` 发送隐藏的后续消息，并对同一工具批次只处理一次，避免重复压缩或消息风暴。
+- **版本门禁**：私有同循环适配器仅支持结构验证通过的官方 Pi `0.84.3` `AgentSession`。其他 Host 按配置使用公共降级或关闭自动续跑。
+
+### 3. 按模型启用的联网搜索
 
 对于白名单中的 `openai-responses` 或 `openai-codex-responses` 模型，扩展直接拦截请求载荷：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "private": false,
   "type": "module",
   "description": "OpenAI-focused Pi toolkit providing remote Responses compaction and native Web Search.",
@@ -40,6 +40,8 @@
     "src/config.ts",
     "src/debug.ts",
     "src/details-store.ts",
+    "src/deferred-tool-carryover.ts",
+    "src/inline-compaction.ts",
     "src/extension-runtime.ts",
     "src/native-fallback.ts",
     "src/payload-rewrite.ts",
@@ -72,6 +74,9 @@
     "@earendil-works/pi-coding-agent": ">=0.80.0"
   },
   "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.84.3",
+    "@earendil-works/pi-ai": "0.84.3",
+    "@earendil-works/pi-coding-agent": "0.84.3",
     "@types/node": "24.12.4",
     "bun": "1.2.23",
     "typescript": "5.9.3"

package/src/config.ts

@@ -5,6 +5,7 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import {
 	DEFAULT_COMPACTION_CONFIG,
 	DEFAULT_TOOLKIT_CONFIG,
+	DEFAULT_AUTO_COMPACTION_CONFIG,
 	DEFAULT_WEB_SEARCH_CONFIG,
 	RESPONSES_COMPACT_CAPABLE_APIS,
 	THINKING_LEVELS,
@@ -25,6 +26,7 @@ const COMPACTION_FIELDS = new Set([
 	"remoteCompactModel",
 	"model",
 	"thinkingLevel",
+	"autoCompaction",
 	"responsesApis",
 	"notifyOnLoad",
 	"debug",
@@ -33,6 +35,7 @@ const COMPACTION_FIELDS = new Set([
 	"redactSensitiveData",
 	"artifactRoot",
 ]);
+const AUTO_COMPACTION_FIELDS = new Set(["enabled", "continuation", "unsupportedFallback", "reserveTokens"]);
 const WEB_SEARCH_FIELDS = new Set(["enabled", "models"]);
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -111,6 +114,37 @@ function toThinkingLevel(value: unknown, fieldPath: string, warnings: string[]):
 	return undefined;
 }
 
+function toCompactionContinuation(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+): "inline" | "followUp" | "off" | undefined {
+	if (value === undefined) return undefined;
+	if (value === "inline" || value === "followUp" || value === "off") return value;
+	warnings.push(`Ignoring ${fieldPath}: expected one of inline, followUp, off.`);
+	return undefined;
+}
+
+function toUnsupportedFallback(
+	value: unknown,
+	fieldPath: string,
+	warnings: string[],
+): "followUp" | "off" | undefined {
+	if (value === undefined) return undefined;
+	if (value === "followUp" || value === "off") return value;
+	warnings.push(`Ignoring ${fieldPath}: expected one of followUp, off.`);
+	return undefined;
+}
+
+function toNonNegativeInteger(value: unknown, fieldPath: string, warnings: string[]): number | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value === "number" && Number.isInteger(value) && Number.isFinite(value) && value >= 0) {
+		return value;
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected a non-negative integer.`);
+	return undefined;
+}
+
 function toSupportedApis(
 	value: unknown,
 	fieldPath: string,
@@ -152,6 +186,7 @@ function cloneDefaults(): ToolkitConfig {
 	return {
 		compaction: {
 			...DEFAULT_COMPACTION_CONFIG,
+			autoCompaction: { ...DEFAULT_AUTO_COMPACTION_CONFIG },
 			responsesApis: [...DEFAULT_COMPACTION_CONFIG.responsesApis],
 		},
 		webSearch: {
@@ -161,6 +196,32 @@ function cloneDefaults(): ToolkitConfig {
 	};
 }
 
+function applyAutoCompactionConfig(
+	raw: Record<string, unknown>,
+	resolved: CompactionConfig["autoCompaction"],
+	warnings: string[],
+): void {
+	warnUnknownFields(raw, AUTO_COMPACTION_FIELDS, "compaction.autoCompaction", warnings);
+	resolved.enabled = toBoolean(raw.enabled, "compaction.autoCompaction.enabled", warnings) ?? resolved.enabled;
+	resolved.continuation =
+		toCompactionContinuation(raw.continuation, "compaction.autoCompaction.continuation", warnings) ??
+		resolved.continuation;
+	resolved.unsupportedFallback =
+		toUnsupportedFallback(
+			raw.unsupportedFallback,
+			"compaction.autoCompaction.unsupportedFallback",
+			warnings,
+		) ?? resolved.unsupportedFallback;
+	const reserveTokens = toNonNegativeInteger(
+		raw.reserveTokens,
+		"compaction.autoCompaction.reserveTokens",
+		warnings,
+	);
+	if (reserveTokens !== undefined) {
+		resolved.reserveTokens = reserveTokens;
+	}
+}
+
 function applyCompactionConfig(
 	raw: Record<string, unknown>,
 	resolved: CompactionConfig,
@@ -205,6 +266,14 @@ function applyCompactionConfig(
 	resolved.thinkingLevel =
 		toThinkingLevel(raw.thinkingLevel, "compaction.thinkingLevel", warnings) ?? resolved.thinkingLevel;
 
+	if (raw.autoCompaction !== undefined) {
+		if (isRecord(raw.autoCompaction)) {
+			applyAutoCompactionConfig(raw.autoCompaction, resolved.autoCompaction, warnings);
+		} else {
+			warnings.push("Ignoring compaction.autoCompaction: expected a JSON object.");
+		}
+	}
+
 	const apis = toSupportedApis(
 		raw.responsesApis,
 		"compaction.responsesApis",

package/src/debug.ts

@@ -177,3 +177,61 @@ export function writeDebugArtifact(
 	fs.writeFileSync(filePath, `${JSON.stringify(envelope, null, 2)}\n`, "utf8");
 	return filePath;
 }
+
+/**
+ * Always-written, content-free failure record for an opaque replay failure.
+ *
+ * Unlike regular payload artifacts this is not gated by logProviderPayloads:
+ * a replay failure is a continuity-loss incident, not optional payload logging.
+ * It contains only structural parity signatures and identity metadata; prompt
+ * text, user content, credentials, and encrypted_content are never included
+ * (critical redaction is applied unconditionally).
+ */
+export function writeReplayFailureArtifact(
+	details: {
+		reason: string;
+		parity?: { actual: string[]; expected: string[]; mismatches: string[] };
+		compactionEntryId?: string;
+		provider?: string;
+		api?: string;
+		model?: string;
+	},
+	settings: CompactionConfig,
+	context: ArtifactContext,
+): string | undefined {
+	try {
+		const sessionInfo = toSessionInfo(context);
+		const paths = resolveArtifactPaths(settings, context);
+		const targetDir = selectArtifactDirectory(paths, "provider-request");
+		ensureDir(targetDir);
+
+		const timestamp = new Date().toISOString();
+		const filePath = path.join(targetDir, `${timestamp.replace(/[.:]/g, "-")}-replay-failure.json`);
+		const data = redactCriticalValue({
+			event: "before_provider_request.rewrite-failed",
+			reason: details.reason,
+			parity: details.parity,
+			compactionEntryId: details.compactionEntryId,
+			provider: details.provider,
+			api: details.api,
+			model: details.model,
+		});
+		const envelope: DebugArtifactEnvelope = {
+			extension: COMPACTION_EXTENSION_ID,
+			kind: "provider-request",
+			timestamp,
+			cwd: sessionInfo.cwd,
+			sessionId: sessionInfo.sessionId,
+			sessionFile: sessionInfo.sessionFile,
+			sessionDir: sessionInfo.sessionDir,
+			redaction: { enabled: true },
+			data,
+		};
+		fs.writeFileSync(filePath, `${JSON.stringify(envelope, null, 2)}\n`, "utf8");
+		return filePath;
+	} catch {
+		// The replay failure path itself must never be masked by an artifact write
+		// error; the caller still aborts the provider request.
+		return undefined;
+	}
+}

package/src/deferred-tool-carryover.ts

@@ -0,0 +1,280 @@
+import type { ResponsesCompatibleRequestPayload } from "./runtime";
+import { isDeferredToolCarryover, type DeferredToolCarryoverV1 } from "./types";
+
+type JsonObject = Record<string, unknown>;
+
+type DeferredToolCompat = {
+	supportsAdditionalTools?: boolean;
+	supportsToolSearch?: boolean;
+};
+
+export type DeferredToolCarryoverMode = "additional-tools" | "tool-search";
+
+export type DeferredToolCarryoverRewrite = {
+	payload: ResponsesCompatibleRequestPayload;
+	changed: boolean;
+	mode?: DeferredToolCarryoverMode;
+	movedToolNames: string[];
+};
+
+function isRecord(value: unknown): value is JsonObject {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function getDeferredToolName(value: unknown): string | undefined {
+	if (!isRecord(value) || (value.type !== "function" && value.type !== "custom")) {
+		return undefined;
+	}
+
+	return typeof value.name === "string" && value.name.trim().length > 0 ? value.name : undefined;
+}
+
+function hasOptionalBooleanField(value: JsonObject, field: string): boolean {
+	return value[field] === undefined || typeof value[field] === "boolean";
+}
+
+function hasOptionalBooleanOrNullField(value: JsonObject, field: string): boolean {
+	return value[field] === undefined || value[field] === null || typeof value[field] === "boolean";
+}
+
+function isCustomToolFormat(value: unknown): boolean {
+	if (!isRecord(value)) return false;
+	if (value.type === "text") return true;
+	return (
+		value.type === "grammar" &&
+		(value.syntax === "lark" || value.syntax === "regex") &&
+		typeof value.definition === "string"
+	);
+}
+
+/** Validate only the provider-facing function/custom shapes emitted by official Pi. */
+function isDeferredToolSchema(value: unknown): value is JsonObject {
+	const name = getDeferredToolName(value);
+	if (!name || !isRecord(value)) return false;
+
+	if (value.type === "function") {
+		return (
+			"parameters" in value &&
+			(value.parameters === null || isRecord(value.parameters)) &&
+			hasOptionalBooleanOrNullField(value, "strict") &&
+			hasOptionalBooleanField(value, "defer_loading") &&
+			(value.description === undefined || value.description === null || typeof value.description === "string")
+		);
+	}
+
+	return (
+		hasOptionalBooleanField(value, "defer_loading") &&
+		(value.description === undefined || typeof value.description === "string") &&
+		(value.format === undefined || isCustomToolFormat(value.format))
+	);
+}
+
+function addLoadedToolSchemas(tools: unknown, loaded: Set<string>): boolean {
+	if (!Array.isArray(tools)) return false;
+	for (const tool of tools) {
+		const name = getDeferredToolName(tool);
+		if (!name || !isDeferredToolSchema(tool)) return false;
+		loaded.add(name);
+	}
+	return true;
+}
+
+function isCompletedClientToolSearchCall(value: JsonObject): value is JsonObject & { call_id: string } {
+	if (
+		value.type !== "tool_search_call" ||
+		typeof value.call_id !== "string" ||
+		value.call_id.length === 0 ||
+		value.execution !== "client" ||
+		value.status !== "completed" ||
+		!isRecord(value.arguments)
+	) {
+		return false;
+	}
+
+	return (
+		typeof value.arguments.query === "string" &&
+		typeof value.arguments.limit === "number" &&
+		Number.isInteger(value.arguments.limit) &&
+		value.arguments.limit >= 0
+	);
+}
+
+function collectLoadedToolNames(input: readonly unknown[], startIndex: number): Set<string> | undefined {
+	const loaded = new Set<string>();
+
+	for (let index = startIndex; index < input.length; index += 1) {
+		const item = input[index];
+		if (!isRecord(item)) continue;
+
+		if (item.type === "additional_tools") {
+			if (item.role !== "developer" || !addLoadedToolSchemas(item.tools, loaded)) return undefined;
+			continue;
+		}
+
+		if (item.type === "tool_search_call") {
+			if (!isCompletedClientToolSearchCall(item)) return undefined;
+			const output = input[index + 1];
+			if (
+				!isRecord(output) ||
+				output.type !== "tool_search_output" ||
+				output.call_id !== item.call_id ||
+				output.execution !== "client" ||
+				output.status !== "completed" ||
+				!addLoadedToolSchemas(output.tools, loaded)
+			) {
+				return undefined;
+			}
+			index += 1;
+			continue;
+		}
+
+		if (item.type === "tool_search_output") return undefined;
+	}
+
+	return loaded;
+}
+
+function createToolSearchCallId(compactionEntryId: string, names: readonly string[]): string {
+	let hash = 2166136261;
+	for (const value of `${compactionEntryId}\u0000${names.join("\u0000")}`) {
+		hash ^= value.codePointAt(0) ?? 0;
+		hash = Math.imul(hash, 16777619);
+	}
+	return `pi_tool_load_${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+function cloneTool(value: JsonObject): JsonObject | undefined {
+	try {
+		return structuredClone(value);
+	} catch {
+		return undefined;
+	}
+}
+
+function selectMode(compat: DeferredToolCompat | undefined): DeferredToolCarryoverMode | undefined {
+	if (compat?.supportsAdditionalTools === true) return "additional-tools";
+	if (compat?.supportsToolSearch === true) return "tool-search";
+	return undefined;
+}
+
+function createLoadPoint(
+	mode: DeferredToolCarryoverMode,
+	compactionEntryId: string,
+	schemas: readonly JsonObject[],
+): JsonObject[] | undefined {
+	const clonedSchemas: JsonObject[] = [];
+	for (const schema of schemas) {
+		const clone = cloneTool(schema);
+		if (!clone) return undefined;
+		if (mode === "tool-search") clone.defer_loading = true;
+		clonedSchemas.push(clone);
+	}
+
+	if (mode === "additional-tools") {
+		return [{ type: "additional_tools", role: "developer", tools: clonedSchemas }];
+	}
+
+	const names = clonedSchemas.map((schema) => getDeferredToolName(schema));
+	if (names.some((name): name is undefined => name === undefined)) return undefined;
+	const callId = createToolSearchCallId(compactionEntryId, names as string[]);
+	return [
+		{
+			type: "tool_search_call",
+			call_id: callId,
+			execution: "client",
+			status: "completed",
+			arguments: { query: (names as string[]).join(" "), limit: names.length },
+		},
+		{
+			type: "tool_search_output",
+			call_id: callId,
+			execution: "client",
+			status: "completed",
+			tools: clonedSchemas,
+		},
+	];
+}
+
+/**
+ * Restore cache-stack's activated function/custom schemas after an opaque
+ * compaction checkpoint. This is deliberately fail-open: malformed state or
+ * payloads leave the provider request untouched so Pi keeps its immediate-tool
+ * fallback behavior.
+ */
+export function rewritePayloadWithDeferredToolCarryover(args: {
+	payload: ResponsesCompatibleRequestPayload;
+	carryover?: DeferredToolCarryoverV1;
+	compactionEntryId: string;
+	checkpointEndIndex: number;
+	compat?: DeferredToolCompat;
+}): DeferredToolCarryoverRewrite {
+	const unchanged: DeferredToolCarryoverRewrite = {
+		payload: args.payload,
+		changed: false,
+		movedToolNames: [],
+	};
+
+	const mode = selectMode(args.compat);
+	if (!mode || !args.carryover || !isDeferredToolCarryover(args.carryover) || !Array.isArray(args.payload.input)) {
+		return unchanged;
+	}
+	if (!Number.isInteger(args.checkpointEndIndex) || args.checkpointEndIndex < 0 || args.checkpointEndIndex > args.payload.input.length) {
+		return unchanged;
+	}
+	if (!Array.isArray(args.payload.tools)) return unchanged;
+
+	const carryoverNames = new Set(
+		args.carryover.toolNames
+			.map((name) => name.trim())
+			.filter((name) => name.length > 0 && name !== "web_search"),
+	);
+	if (carryoverNames.size === 0) return unchanged;
+
+	const schemasByName = new Map<string, JsonObject>();
+	const duplicateNames = new Set<string>();
+	for (const tool of args.payload.tools) {
+		const name = getDeferredToolName(tool);
+		if (!name || !carryoverNames.has(name)) continue;
+		if (!isDeferredToolSchema(tool)) return unchanged;
+		const schema = tool;
+		if (schemasByName.has(name)) {
+			duplicateNames.add(name);
+			continue;
+		}
+		schemasByName.set(name, schema);
+	}
+	for (const name of duplicateNames) schemasByName.delete(name);
+	if (schemasByName.size === 0) return unchanged;
+
+	const loadedNames = collectLoadedToolNames(args.payload.input, args.checkpointEndIndex);
+	if (!loadedNames) return unchanged;
+	const matchingNames = [...schemasByName.keys()];
+	const movedNames = matchingNames.filter((name) => !loadedNames.has(name));
+	const matchingNameSet = new Set(matchingNames);
+	const nextTools = args.payload.tools.filter((tool) => {
+		const name = getDeferredToolName(tool);
+		return !name || !matchingNameSet.has(name);
+	});
+	const toolsChanged = nextTools.length !== args.payload.tools.length;
+	if (movedNames.length === 0 && !toolsChanged) return unchanged;
+
+	const nextInput = [...args.payload.input];
+	if (movedNames.length > 0) {
+		const schemas = movedNames.map((name) => schemasByName.get(name));
+		if (schemas.some((schema): schema is undefined => schema === undefined)) return unchanged;
+		const loadPoint = createLoadPoint(mode, args.compactionEntryId, schemas as JsonObject[]);
+		if (!loadPoint) return unchanged;
+		nextInput.splice(args.checkpointEndIndex, 0, ...loadPoint);
+	}
+
+	return {
+		payload: {
+			...args.payload,
+			tools: nextTools,
+			input: nextInput,
+		},
+		changed: true,
+		mode,
+		movedToolNames: movedNames,
+	};
+}