pi-openai-toolkit 0.24.1 → 0.24.2

package/src/types.ts

@@ -1,541 +1,541 @@
-import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { ConfigDocumentSnapshot } from "./config/policy";
-import type { CompactionEntry, CompactionResult, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
-
-export const TOOLKIT_ID = "pi-openai-toolkit";
-export const COMPACTION_EXTENSION_ID = `${TOOLKIT_ID}:compaction`;
-export const WEB_SEARCH_EXTENSION_ID = `${TOOLKIT_ID}:web-search`;
-export const IMAGE_GENERATION_EXTENSION_ID = `${TOOLKIT_ID}:image-generation`;
-export const DEFAULT_ARTIFACT_ROOT = "~/.pi/agent/artifacts/pi-openai-toolkit/compaction";
-export const REDACTED_VALUE = "[REDACTED]";
-/**
- * APIs the extension knows how to build a `/responses/compact` URL for.
- * `compaction.responsesApis` in config.json may only narrow this set.
- */
-export const RESPONSES_COMPACT_CAPABLE_APIS = [
-	"openai-responses",
-	"openai-codex-responses",
-	"azure-openai-responses",
-] as const;
-/**
- * Bare model ID used by the independent Astra effort compatibility layer.
- * Gateway transport is an independent exact-model opt-in; this constant
- * does not verify backend support or grant that opt-in.
- */
-export const ASTRA_MODEL_ID = "gpt-6-astra";
-export const LEGACY_NATIVE_COMPACTION_STRATEGY = "openai-native-compact-v1";
-export const REMOTE_V2_COMPACTION_STRATEGY = "openai-remote-compaction-v2";
-export const NATIVE_COMPACTION_STRATEGY = REMOTE_V2_COMPACTION_STRATEGY;
-/**
- * Provenance recorded when the checkpoint input came from Pi's ordered context
- * hook projection. Older persisted entries may omit it and must not be
- * replayed by Remote V2.
- */
-export const NATIVE_COMPACTION_INPUT_PROVENANCE = "pi-context-hook-v1" as const;
-/** Explicit opt-in marker for the pre-projection raw session/branch chain. */
-export const LEGACY_REMOTE_V2_INPUT_PROVENANCE = "legacy-raw-context-v1" as const;
-export type NativeCompactionInputProvenance =
-	| typeof NATIVE_COMPACTION_INPUT_PROVENANCE
-	| typeof LEGACY_REMOTE_V2_INPUT_PROVENANCE;
-/**
- * Pi currently requires CompactionResult.summary to be text. This marker is only a
- * replay shim; the provider receives the opaque item from details.compactedWindow.
- */
-export const NATIVE_COMPACTION_FALLBACK_SUMMARY = "[OpenAI remote v2 opaque compaction checkpoint]";
-export const STANDALONE_COMPACTION_FALLBACK_SUMMARY = "[OpenAI standalone opaque compaction window]";
-
-export const THINKING_LEVELS: readonly ThinkingLevel[] = [
-	"off",
-	"minimal",
-	"low",
-	"medium",
-	"high",
-	"xhigh",
-	"max",
-];
-
-export type DebugArtifactKind =
-	| "provider-request"
-	| "compact-response"
-	| "compaction-event"
-	| "lifecycle";
-
-/** How Remote V2 obtains the history it sends to the compaction endpoint. */
-export type RemoteV2ContextSource = "pi-context-hook" | "legacy";
-
-/** Native-method fallback compaction: which model runs pi's compact() and how deeply. */
-export type NativeFallbackConfig = {
-	enabled: boolean;
-	/**
-	 * "provider/model-id" used for native-method fallback compaction when the active model
-	 * cannot use remote v2 at all. A failed remote request is instead summarized by
-	 * `remoteCompactModel`; the two sources never substitute for each other. Unset means the
-	 * active model via pi's default path.
-	 */
-	model?: string;
-	/** Thinking level passed to pi's native compact() when the fallback model runs. */
-	thinkingLevel: ThinkingLevel;
-};
-
-export type DebugConfig = {
-	debug: boolean;
-	notifyOnLoad: boolean;
-	logProviderPayloads: boolean;
-	logCompactResponses: boolean;
-	redactSensitiveData: boolean;
-	artifactRoot: string;
-};
-
-export type CompactionConfig = {
-	enabled: boolean;
-	/**
-	 * Allow a Responses session whose latest compaction was not created by this extension
-	 * to restart native compaction from Pi's current serialized session context.
-	 */
-	allowCompactionContinuityBreak: boolean;
-	/**
-	 * "provider/model-id" used only for remote_compaction_v2. The active session model
-	 * remains the checkpoint consumer and continues handling normal requests.
-	 */
-	remoteCompactModel?: string;
-	/**
-	 * Remote V2 input source. Pi's patched context hook preserves the normal
-	 * provider-visible projection; legacy keeps the pre-patch raw session/branch chain.
-	 */
-	remoteV2ContextSource: RemoteV2ContextSource;
-	/** Native-method fallback compaction policy (non-Responses APIs, or when the compact endpoint fails). */
-	nativeFallback: NativeFallbackConfig;
-	/**
-	 * Subset of RESPONSES_COMPACT_CAPABLE_APIS that should use remote compaction.
-	 */
-	responsesApis: string[];
-	/**
-	 * Legacy alias for exact "provider/model" Codex gateway transport opt-ins.
-	 * Shared by compaction and image generation; not a window capability.
-	 */
-	gatewayContextModels: string[];
-	notifyOnLoad: boolean;
-	debug: boolean;
-	logProviderPayloads: boolean;
-	logCompactResponses: boolean;
-	redactSensitiveData: boolean;
-	artifactRoot: string;
-};
-
-export type WebSearchRoute = "local" | "hosted" | "standalone-alpha";
-
-export type WebSearchConfig = {
-	enabled: boolean;
-	/** Exact provider/model keys allowed to use toolkit-native Web Search. */
-	models: string[];
-	/** Explicit route for every model not matched by `routes`. */
-	defaultRoute?: WebSearchRoute;
-	/** Exact `provider/model-id` overrides; no globs or fuzzy matching. */
-	routes?: Record<string, WebSearchRoute>;
-};
-
-export type ImageGenerationConfig = {
-	enabled: boolean;
-	/**
-	 * Bare Images API model ids this toolkit may send, without a `provider/` prefix.
-	 * The first legacy entry is the default; `openai_generate_image`'s optional `model` argument
-	 * may select any other entry in this order-preserving list.
-	 */
-	models: string[];
-};
-
-export type ToolkitConfig = {
-	compaction: CompactionConfig;
-	webSearch: WebSearchConfig;
-	imageGeneration: ImageGenerationConfig;
-};
-
-export type LoadedToolkitConfig = {
-	/** Legacy normalization seam. Feature entrypoints must resolve this snapshot for their model. */
-	config: ToolkitConfig;
-	/** Optional only for existing injected legacy readers; real loads always include it. */
-	document?: ConfigDocumentSnapshot;
-	/** Path of the config file that was applied, if it existed and parsed. */
-	source?: string;
-	warnings: string[];
-};
-
-export type ArtifactPaths = {
-	rootDir: string;
-	sessionDir: string;
-	providerRequestsDir: string;
-	compactResponsesDir: string;
-	compactionDir: string;
-	lifecycleDir: string;
-};
-
-export type ArtifactSessionInfo = {
-	cwd: string;
-	sessionId?: string;
-	sessionFile?: string;
-	sessionDir?: string;
-};
-
-export type ArtifactContext = ArtifactSessionInfo | Pick<ExtensionContext, "cwd" | "sessionManager">;
-
-export type DebugArtifactEnvelope = {
-	extension: string;
-	kind: DebugArtifactKind;
-	timestamp: string;
-	cwd: string;
-	sessionId?: string;
-	sessionFile?: string;
-	sessionDir?: string;
-	redaction: {
-		enabled: boolean;
-	};
-	data: unknown;
-};
-
-export type RedactOptions = {
-	placeholder?: string;
-};
-
-export type NativeCompactionStrategy =
-	| typeof LEGACY_NATIVE_COMPACTION_STRATEGY
-	| typeof REMOTE_V2_COMPACTION_STRATEGY;
-
-export type NativeCompactionRequestMeta = {
-	tokensBefore?: number;
-	previousSummaryPresent?: boolean;
-};
-
-export type NativeCompactionIdentity = {
-	provider: string;
-	api: string;
-	model: string;
-	baseUrl: string;
-};
-
-export const CACHE_STACK_ACTIVATION_ENTRY_TYPE = "pi-cache-stack.activation-state.v1" as const;
-
-export type DeferredToolCarryoverV1 = {
-	version: 1;
-	source: typeof CACHE_STACK_ACTIVATION_ENTRY_TYPE;
-	toolNames: string[];
-	catalogHash?: string;
-};
-
-export type NativeCompactionDetails = NativeCompactionIdentity & {
-	strategy: NativeCompactionStrategy;
-	/**
-	 * Input source recorded for checkpoints created by this extension. Older
-	 * persisted entries may omit it and must not be treated as verified for
-	 * Remote V2 replay.
-	 */
-	inputProvenance?: NativeCompactionInputProvenance;
-	/** Actual producer of the opaque checkpoint; absent on legacy same-model entries. */
-	compactionModel?: NativeCompactionIdentity;
-	/** Cache-stack activation state captured at this opaque checkpoint. */
-	deferredToolCarryover?: DeferredToolCarryoverV1;
-	compactedWindow: unknown[];
-	compactResponseId?: string;
-	createdAt: string;
-	requestMeta?: NativeCompactionRequestMeta;
-};
-
-export type NativeCompactionEntry = CompactionEntry<NativeCompactionDetails>;
-
-export type CreateNativeCompactionDetailsInput = NativeCompactionIdentity & {
-	strategy?: NativeCompactionStrategy;
-	inputProvenance: NativeCompactionInputProvenance;
-	compactionModel?: NativeCompactionIdentity;
-	deferredToolCarryover?: DeferredToolCarryoverV1;
-	compactedWindow: unknown[];
-	compactResponseId?: string;
-	createdAt?: string;
-	requestMeta?: NativeCompactionRequestMeta;
-};
-
-export type CreateNativeCompactionResultInput = {
-	firstKeptEntryId: string;
-	tokensBefore: number;
-	details: NativeCompactionDetails;
-	/**
-	 * An explicitly supplied genuine summary. Retained standalone assistant text is
-	 * not a summary of the sealed history; ordinary remote success uses an opaque marker.
-	 */
-	summary?: string;
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-function isNonEmptyString(value: unknown): value is string {
-	return typeof value === "string" && value.trim().length > 0;
-}
-
-function isFiniteNonNegativeNumber(value: unknown): value is number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0;
-}
-
-function normalizeString(value: string): string {
-	return value.trim();
-}
-
-function isStructuredValue(value: unknown): boolean {
-	if (
-		value === null ||
-		typeof value === "string" ||
-		(typeof value === "number" && Number.isFinite(value)) ||
-		typeof value === "boolean"
-	) {
-		return true;
-	}
-
-	if (Array.isArray(value)) {
-		return value.every(isStructuredValue);
-	}
-
-	if (isRecord(value)) {
-		return Object.values(value).every(isStructuredValue);
-	}
-
-	return false;
-}
-
-function cloneStructuredValue(value: unknown): unknown {
-	if (
-		value === null ||
-		typeof value === "string" ||
-		typeof value === "number" ||
-		typeof value === "boolean"
-	) {
-		return value;
-	}
-
-	if (Array.isArray(value)) {
-		return value.map(cloneStructuredValue);
-	}
-
-	if (isRecord(value)) {
-		return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, cloneStructuredValue(nested)]));
-	}
-
-	throw new Error(`Unsupported structured value: ${typeof value}`);
-}
-
-export function isCompactedWindowItem(value: unknown): value is Record<string, unknown> {
-	return isRecord(value) && Object.values(value).every(isStructuredValue);
-}
-
-export function isNativeCompactionRequestMeta(value: unknown): value is NativeCompactionRequestMeta {
-	if (!isRecord(value)) {
-		return false;
-	}
-
-	const { tokensBefore, previousSummaryPresent } = value;
-	if (tokensBefore !== undefined && !isFiniteNonNegativeNumber(tokensBefore)) {
-		return false;
-	}
-
-	if (previousSummaryPresent !== undefined && typeof previousSummaryPresent !== "boolean") {
-		return false;
-	}
-
-	return true;
-}
-
-export function isNativeCompactionIdentity(value: unknown): value is NativeCompactionIdentity {
-	if (!isRecord(value)) {
-		return false;
-	}
-
-	return (
-		isNonEmptyString(value.provider) &&
-		isNonEmptyString(value.api) &&
-		isNonEmptyString(value.model) &&
-		isNonEmptyString(value.baseUrl)
-	);
-}
-
-export function isNativeCompactionInputProvenance(value: unknown): value is NativeCompactionInputProvenance {
-	return value === NATIVE_COMPACTION_INPUT_PROVENANCE || value === LEGACY_REMOTE_V2_INPUT_PROVENANCE;
-}
-
-export function getRemoteV2InputProvenance(source: RemoteV2ContextSource): NativeCompactionInputProvenance {
-	return source === "pi-context-hook"
-		? NATIVE_COMPACTION_INPUT_PROVENANCE
-		: LEGACY_REMOTE_V2_INPUT_PROVENANCE;
-}
-
-export function isDeferredToolCarryover(value: unknown): value is DeferredToolCarryoverV1 {
-	if (!isRecord(value) || value.version !== 1 || value.source !== CACHE_STACK_ACTIVATION_ENTRY_TYPE) {
-		return false;
-	}
-
-	return (
-		Array.isArray(value.toolNames) &&
-		value.toolNames.every((name) => isNonEmptyString(name)) &&
-		(value.catalogHash === undefined || typeof value.catalogHash === "string")
-	);
-}
-
-function normalizeDeferredToolCarryover(value: DeferredToolCarryoverV1): DeferredToolCarryoverV1 {
-	if (!isDeferredToolCarryover(value)) {
-		throw new Error("Invalid deferred tool carryover");
-	}
-
-	return {
-		version: 1,
-		source: CACHE_STACK_ACTIVATION_ENTRY_TYPE,
-		toolNames: [...new Set(value.toolNames.map((name) => name.trim()).filter(Boolean))].sort(),
-		...(typeof value.catalogHash === "string" ? { catalogHash: value.catalogHash } : {}),
-	};
-}
-
-function decodeCacheStackActivationState(value: unknown): DeferredToolCarryoverV1 | undefined {
-	if (!isRecord(value) || value.version !== 1 || typeof value.catalogHash !== "string") {
-		return undefined;
-	}
-	if (!Array.isArray(value.activatedTools) || !value.activatedTools.every((name) => typeof name === "string")) {
-		return undefined;
-	}
-
-	return normalizeDeferredToolCarryover({
-		version: 1,
-		source: CACHE_STACK_ACTIVATION_ENTRY_TYPE,
-		toolNames: value.activatedTools,
-		catalogHash: value.catalogHash,
-	});
-}
-
-/** Read only the latest valid cache-stack activation snapshot on this branch. */
-export function getLatestDeferredToolCarryover(
-	entries: readonly SessionEntry[],
-): DeferredToolCarryoverV1 | undefined {
-	for (let index = entries.length - 1; index >= 0; index -= 1) {
-		const entry = entries[index];
-		if (entry?.type !== "custom" || entry.customType !== CACHE_STACK_ACTIVATION_ENTRY_TYPE) {
-			continue;
-		}
-
-		const decoded = decodeCacheStackActivationState(entry.data);
-		if (decoded) return decoded;
-	}
-
-	return undefined;
-}
-
-export function isNativeCompactionDetails(value: unknown): value is NativeCompactionDetails {
-	if (!isRecord(value) || !isNativeCompactionIdentity(value)) {
-		return false;
-	}
-
-	const candidate = value as Record<string, unknown>;
-	return (
-		(candidate.strategy === LEGACY_NATIVE_COMPACTION_STRATEGY ||
-			candidate.strategy === REMOTE_V2_COMPACTION_STRATEGY) &&
-		(candidate.inputProvenance === undefined || isNativeCompactionInputProvenance(candidate.inputProvenance)) &&
-		(candidate.compactionModel === undefined || isNativeCompactionIdentity(candidate.compactionModel)) &&
-		(candidate.deferredToolCarryover === undefined || isDeferredToolCarryover(candidate.deferredToolCarryover)) &&
-		Array.isArray(candidate.compactedWindow) &&
-		candidate.compactedWindow.every(isCompactedWindowItem) &&
-		isNonEmptyString(candidate.createdAt) &&
-		(candidate.compactResponseId === undefined || isNonEmptyString(candidate.compactResponseId)) &&
-		(candidate.requestMeta === undefined || isNativeCompactionRequestMeta(candidate.requestMeta))
-	);
-}
-
-export function isNativeCompactionEntry(value: unknown): value is NativeCompactionEntry {
-	return isRecord(value) && value.type === "compaction" && isNativeCompactionDetails(value.details);
-}
-
-export function createNativeCompactionDetails(input: CreateNativeCompactionDetailsInput): NativeCompactionDetails {
-	if (input.strategy !== undefined && input.strategy !== LEGACY_NATIVE_COMPACTION_STRATEGY && input.strategy !== REMOTE_V2_COMPACTION_STRATEGY) {
-		throw new Error("Invalid native compaction strategy");
-	}
-	return {
-		strategy: input.strategy ?? NATIVE_COMPACTION_STRATEGY,
-		inputProvenance: input.inputProvenance,
-		provider: normalizeString(input.provider),
-		api: normalizeString(input.api),
-		model: normalizeString(input.model),
-		baseUrl: normalizeString(input.baseUrl),
-		compactionModel: input.compactionModel
-			? {
-				provider: normalizeString(input.compactionModel.provider),
-				api: normalizeString(input.compactionModel.api),
-				model: normalizeString(input.compactionModel.model),
-				baseUrl: normalizeString(input.compactionModel.baseUrl),
-			}
-			: undefined,
-		deferredToolCarryover: input.deferredToolCarryover
-			? normalizeDeferredToolCarryover(input.deferredToolCarryover)
-			: undefined,
-		compactedWindow: input.compactedWindow.map((item) => cloneStructuredValue(item)),
-		compactResponseId: isNonEmptyString(input.compactResponseId) ? normalizeString(input.compactResponseId) : undefined,
-		createdAt: isNonEmptyString(input.createdAt) ? normalizeString(input.createdAt) : new Date().toISOString(),
-		requestMeta: input.requestMeta
-			? {
-				...(input.requestMeta.tokensBefore !== undefined ? { tokensBefore: input.requestMeta.tokensBefore } : {}),
-				...(input.requestMeta.previousSummaryPresent !== undefined
-					? { previousSummaryPresent: input.requestMeta.previousSummaryPresent }
-					: {}),
-			}
-			: undefined,
-	};
-}
-
-export function createNativeCompactionResult(
-	input: CreateNativeCompactionResultInput,
-): CompactionResult<NativeCompactionDetails> {
-	const summary = input.summary?.trim();
-	return {
-		summary: summary && summary.length > 0 ? summary
-			: input.details.strategy === LEGACY_NATIVE_COMPACTION_STRATEGY ? STANDALONE_COMPACTION_FALLBACK_SUMMARY
-			: NATIVE_COMPACTION_FALLBACK_SUMMARY,
-		firstKeptEntryId: input.firstKeptEntryId,
-		tokensBefore: input.tokensBefore,
-		details: input.details,
-	};
-}
-
-export const DEFAULT_NATIVE_FALLBACK_CONFIG: NativeFallbackConfig = {
-	enabled: true,
-	model: undefined,
-	thinkingLevel: "off",
-};
-
-export const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
-	enabled: true,
-	allowCompactionContinuityBreak: false,
-	remoteCompactModel: undefined,
-	remoteV2ContextSource: "legacy",
-
-	nativeFallback: { ...DEFAULT_NATIVE_FALLBACK_CONFIG },
-	responsesApis: [...RESPONSES_COMPACT_CAPABLE_APIS],
-	gatewayContextModels: [],
-	notifyOnLoad: false,
-	debug: false,
-	logProviderPayloads: false,
-	logCompactResponses: false,
-	redactSensitiveData: true,
-	artifactRoot: DEFAULT_ARTIFACT_ROOT,
-};
-
-export const DEFAULT_WEB_SEARCH_CONFIG: WebSearchConfig = {
-	enabled: true,
-	models: [],
-};
-
-/** Single source of truth for the hosted image model used when nothing is configured. */
-export const DEFAULT_IMAGE_GENERATION_MODEL = "grok-imagine-image-2.0";
-export const DEFAULT_IMAGE_GENERATION_MODELS: readonly string[] = [DEFAULT_IMAGE_GENERATION_MODEL];
-
-export const DEFAULT_IMAGE_GENERATION_CONFIG: ImageGenerationConfig = {
-	enabled: false,
-	models: [...DEFAULT_IMAGE_GENERATION_MODELS],
-};
-
-export const DEFAULT_TOOLKIT_CONFIG: ToolkitConfig = {
-	compaction: DEFAULT_COMPACTION_CONFIG,
-	webSearch: DEFAULT_WEB_SEARCH_CONFIG,
-	imageGeneration: DEFAULT_IMAGE_GENERATION_CONFIG,
-};
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { ConfigDocumentSnapshot } from "./config/policy";
+import type { CompactionEntry, CompactionResult, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export const TOOLKIT_ID = "pi-openai-toolkit";
+export const COMPACTION_EXTENSION_ID = `${TOOLKIT_ID}:compaction`;
+export const WEB_SEARCH_EXTENSION_ID = `${TOOLKIT_ID}:web-search`;
+export const IMAGE_GENERATION_EXTENSION_ID = `${TOOLKIT_ID}:image-generation`;
+export const DEFAULT_ARTIFACT_ROOT = "~/.pi/agent/artifacts/pi-openai-toolkit/compaction";
+export const REDACTED_VALUE = "[REDACTED]";
+/**
+ * APIs the extension knows how to build a `/responses/compact` URL for.
+ * `compaction.responsesApis` in config.json may only narrow this set.
+ */
+export const RESPONSES_COMPACT_CAPABLE_APIS = [
+	"openai-responses",
+	"openai-codex-responses",
+	"azure-openai-responses",
+] as const;
+/**
+ * Bare model ID used by the independent Astra effort compatibility layer.
+ * Gateway transport is an independent exact-model opt-in; this constant
+ * does not verify backend support or grant that opt-in.
+ */
+export const ASTRA_MODEL_ID = "gpt-6-astra";
+export const LEGACY_NATIVE_COMPACTION_STRATEGY = "openai-native-compact-v1";
+export const REMOTE_V2_COMPACTION_STRATEGY = "openai-remote-compaction-v2";
+export const NATIVE_COMPACTION_STRATEGY = REMOTE_V2_COMPACTION_STRATEGY;
+/**
+ * Provenance recorded when the checkpoint input came from Pi's ordered context
+ * hook projection. Older persisted entries may omit it and must not be
+ * replayed by Remote V2.
+ */
+export const NATIVE_COMPACTION_INPUT_PROVENANCE = "pi-context-hook-v1" as const;
+/** Explicit opt-in marker for the pre-projection raw session/branch chain. */
+export const LEGACY_REMOTE_V2_INPUT_PROVENANCE = "legacy-raw-context-v1" as const;
+export type NativeCompactionInputProvenance =
+	| typeof NATIVE_COMPACTION_INPUT_PROVENANCE
+	| typeof LEGACY_REMOTE_V2_INPUT_PROVENANCE;
+/**
+ * Pi currently requires CompactionResult.summary to be text. This marker is only a
+ * replay shim; the provider receives the opaque item from details.compactedWindow.
+ */
+export const NATIVE_COMPACTION_FALLBACK_SUMMARY = "[OpenAI remote v2 opaque compaction checkpoint]";
+export const STANDALONE_COMPACTION_FALLBACK_SUMMARY = "[OpenAI standalone opaque compaction window]";
+
+export const THINKING_LEVELS: readonly ThinkingLevel[] = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+];
+
+export type DebugArtifactKind =
+	| "provider-request"
+	| "compact-response"
+	| "compaction-event"
+	| "lifecycle";
+
+/** How Remote V2 obtains the history it sends to the compaction endpoint. */
+export type RemoteV2ContextSource = "pi-context-hook" | "legacy";
+
+/** Native-method fallback compaction: which model runs pi's compact() and how deeply. */
+export type NativeFallbackConfig = {
+	enabled: boolean;
+	/**
+	 * "provider/model-id" used for native-method fallback compaction when the active model
+	 * cannot use remote v2 at all. A failed remote request is instead summarized by
+	 * `remoteCompactModel`; the two sources never substitute for each other. Unset means the
+	 * active model via pi's default path.
+	 */
+	model?: string;
+	/** Thinking level passed to pi's native compact() when the fallback model runs. */
+	thinkingLevel: ThinkingLevel;
+};
+
+export type DebugConfig = {
+	debug: boolean;
+	notifyOnLoad: boolean;
+	logProviderPayloads: boolean;
+	logCompactResponses: boolean;
+	redactSensitiveData: boolean;
+	artifactRoot: string;
+};
+
+export type CompactionConfig = {
+	enabled: boolean;
+	/**
+	 * Allow a Responses session whose latest compaction was not created by this extension
+	 * to restart native compaction from Pi's current serialized session context.
+	 */
+	allowCompactionContinuityBreak: boolean;
+	/**
+	 * "provider/model-id" used only for remote_compaction_v2. The active session model
+	 * remains the checkpoint consumer and continues handling normal requests.
+	 */
+	remoteCompactModel?: string;
+	/**
+	 * Remote V2 input source. Pi's patched context hook preserves the normal
+	 * provider-visible projection; legacy keeps the pre-patch raw session/branch chain.
+	 */
+	remoteV2ContextSource: RemoteV2ContextSource;
+	/** Native-method fallback compaction policy (non-Responses APIs, or when the compact endpoint fails). */
+	nativeFallback: NativeFallbackConfig;
+	/**
+	 * Subset of RESPONSES_COMPACT_CAPABLE_APIS that should use remote compaction.
+	 */
+	responsesApis: string[];
+	/**
+	 * Legacy alias for exact "provider/model" Codex gateway transport opt-ins.
+	 * Shared by compaction and image generation; not a window capability.
+	 */
+	gatewayContextModels: string[];
+	notifyOnLoad: boolean;
+	debug: boolean;
+	logProviderPayloads: boolean;
+	logCompactResponses: boolean;
+	redactSensitiveData: boolean;
+	artifactRoot: string;
+};
+
+export type WebSearchRoute = "local" | "hosted" | "standalone-alpha";
+
+export type WebSearchConfig = {
+	enabled: boolean;
+	/** Exact provider/model keys allowed to use toolkit-native Web Search. */
+	models: string[];
+	/** Explicit route for every model not matched by `routes`. */
+	defaultRoute?: WebSearchRoute;
+	/** Exact `provider/model-id` overrides; no globs or fuzzy matching. */
+	routes?: Record<string, WebSearchRoute>;
+};
+
+export type ImageGenerationConfig = {
+	enabled: boolean;
+	/**
+	 * Bare Images API model ids this toolkit may send, without a `provider/` prefix.
+	 * The first legacy entry is the default; `openai_generate_image`'s optional `model` argument
+	 * may select any other entry in this order-preserving list.
+	 */
+	models: string[];
+};
+
+export type ToolkitConfig = {
+	compaction: CompactionConfig;
+	webSearch: WebSearchConfig;
+	imageGeneration: ImageGenerationConfig;
+};
+
+export type LoadedToolkitConfig = {
+	/** Legacy normalization seam. Feature entrypoints must resolve this snapshot for their model. */
+	config: ToolkitConfig;
+	/** Optional only for existing injected legacy readers; real loads always include it. */
+	document?: ConfigDocumentSnapshot;
+	/** Path of the config file that was applied, if it existed and parsed. */
+	source?: string;
+	warnings: string[];
+};
+
+export type ArtifactPaths = {
+	rootDir: string;
+	sessionDir: string;
+	providerRequestsDir: string;
+	compactResponsesDir: string;
+	compactionDir: string;
+	lifecycleDir: string;
+};
+
+export type ArtifactSessionInfo = {
+	cwd: string;
+	sessionId?: string;
+	sessionFile?: string;
+	sessionDir?: string;
+};
+
+export type ArtifactContext = ArtifactSessionInfo | Pick<ExtensionContext, "cwd" | "sessionManager">;
+
+export type DebugArtifactEnvelope = {
+	extension: string;
+	kind: DebugArtifactKind;
+	timestamp: string;
+	cwd: string;
+	sessionId?: string;
+	sessionFile?: string;
+	sessionDir?: string;
+	redaction: {
+		enabled: boolean;
+	};
+	data: unknown;
+};
+
+export type RedactOptions = {
+	placeholder?: string;
+};
+
+export type NativeCompactionStrategy =
+	| typeof LEGACY_NATIVE_COMPACTION_STRATEGY
+	| typeof REMOTE_V2_COMPACTION_STRATEGY;
+
+export type NativeCompactionRequestMeta = {
+	tokensBefore?: number;
+	previousSummaryPresent?: boolean;
+};
+
+export type NativeCompactionIdentity = {
+	provider: string;
+	api: string;
+	model: string;
+	baseUrl: string;
+};
+
+export const CACHE_STACK_ACTIVATION_ENTRY_TYPE = "pi-cache-stack.activation-state.v1" as const;
+
+export type DeferredToolCarryoverV1 = {
+	version: 1;
+	source: typeof CACHE_STACK_ACTIVATION_ENTRY_TYPE;
+	toolNames: string[];
+	catalogHash?: string;
+};
+
+export type NativeCompactionDetails = NativeCompactionIdentity & {
+	strategy: NativeCompactionStrategy;
+	/**
+	 * Input source recorded for checkpoints created by this extension. Older
+	 * persisted entries may omit it and must not be treated as verified for
+	 * Remote V2 replay.
+	 */
+	inputProvenance?: NativeCompactionInputProvenance;
+	/** Actual producer of the opaque checkpoint; absent on legacy same-model entries. */
+	compactionModel?: NativeCompactionIdentity;
+	/** Cache-stack activation state captured at this opaque checkpoint. */
+	deferredToolCarryover?: DeferredToolCarryoverV1;
+	compactedWindow: unknown[];
+	compactResponseId?: string;
+	createdAt: string;
+	requestMeta?: NativeCompactionRequestMeta;
+};
+
+export type NativeCompactionEntry = CompactionEntry<NativeCompactionDetails>;
+
+export type CreateNativeCompactionDetailsInput = NativeCompactionIdentity & {
+	strategy?: NativeCompactionStrategy;
+	inputProvenance: NativeCompactionInputProvenance;
+	compactionModel?: NativeCompactionIdentity;
+	deferredToolCarryover?: DeferredToolCarryoverV1;
+	compactedWindow: unknown[];
+	compactResponseId?: string;
+	createdAt?: string;
+	requestMeta?: NativeCompactionRequestMeta;
+};
+
+export type CreateNativeCompactionResultInput = {
+	firstKeptEntryId: string;
+	tokensBefore: number;
+	details: NativeCompactionDetails;
+	/**
+	 * An explicitly supplied genuine summary. Retained standalone assistant text is
+	 * not a summary of the sealed history; ordinary remote success uses an opaque marker.
+	 */
+	summary?: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isFiniteNonNegativeNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function normalizeString(value: string): string {
+	return value.trim();
+}
+
+function isStructuredValue(value: unknown): boolean {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		(typeof value === "number" && Number.isFinite(value)) ||
+		typeof value === "boolean"
+	) {
+		return true;
+	}
+
+	if (Array.isArray(value)) {
+		return value.every(isStructuredValue);
+	}
+
+	if (isRecord(value)) {
+		return Object.values(value).every(isStructuredValue);
+	}
+
+	return false;
+}
+
+function cloneStructuredValue(value: unknown): unknown {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	) {
+		return value;
+	}
+
+	if (Array.isArray(value)) {
+		return value.map(cloneStructuredValue);
+	}
+
+	if (isRecord(value)) {
+		return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, cloneStructuredValue(nested)]));
+	}
+
+	throw new Error(`Unsupported structured value: ${typeof value}`);
+}
+
+export function isCompactedWindowItem(value: unknown): value is Record<string, unknown> {
+	return isRecord(value) && Object.values(value).every(isStructuredValue);
+}
+
+export function isNativeCompactionRequestMeta(value: unknown): value is NativeCompactionRequestMeta {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	const { tokensBefore, previousSummaryPresent } = value;
+	if (tokensBefore !== undefined && !isFiniteNonNegativeNumber(tokensBefore)) {
+		return false;
+	}
+
+	if (previousSummaryPresent !== undefined && typeof previousSummaryPresent !== "boolean") {
+		return false;
+	}
+
+	return true;
+}
+
+export function isNativeCompactionIdentity(value: unknown): value is NativeCompactionIdentity {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	return (
+		isNonEmptyString(value.provider) &&
+		isNonEmptyString(value.api) &&
+		isNonEmptyString(value.model) &&
+		isNonEmptyString(value.baseUrl)
+	);
+}
+
+export function isNativeCompactionInputProvenance(value: unknown): value is NativeCompactionInputProvenance {
+	return value === NATIVE_COMPACTION_INPUT_PROVENANCE || value === LEGACY_REMOTE_V2_INPUT_PROVENANCE;
+}
+
+export function getRemoteV2InputProvenance(source: RemoteV2ContextSource): NativeCompactionInputProvenance {
+	return source === "pi-context-hook"
+		? NATIVE_COMPACTION_INPUT_PROVENANCE
+		: LEGACY_REMOTE_V2_INPUT_PROVENANCE;
+}
+
+export function isDeferredToolCarryover(value: unknown): value is DeferredToolCarryoverV1 {
+	if (!isRecord(value) || value.version !== 1 || value.source !== CACHE_STACK_ACTIVATION_ENTRY_TYPE) {
+		return false;
+	}
+
+	return (
+		Array.isArray(value.toolNames) &&
+		value.toolNames.every((name) => isNonEmptyString(name)) &&
+		(value.catalogHash === undefined || typeof value.catalogHash === "string")
+	);
+}
+
+function normalizeDeferredToolCarryover(value: DeferredToolCarryoverV1): DeferredToolCarryoverV1 {
+	if (!isDeferredToolCarryover(value)) {
+		throw new Error("Invalid deferred tool carryover");
+	}
+
+	return {
+		version: 1,
+		source: CACHE_STACK_ACTIVATION_ENTRY_TYPE,
+		toolNames: [...new Set(value.toolNames.map((name) => name.trim()).filter(Boolean))].sort(),
+		...(typeof value.catalogHash === "string" ? { catalogHash: value.catalogHash } : {}),
+	};
+}
+
+function decodeCacheStackActivationState(value: unknown): DeferredToolCarryoverV1 | undefined {
+	if (!isRecord(value) || value.version !== 1 || typeof value.catalogHash !== "string") {
+		return undefined;
+	}
+	if (!Array.isArray(value.activatedTools) || !value.activatedTools.every((name) => typeof name === "string")) {
+		return undefined;
+	}
+
+	return normalizeDeferredToolCarryover({
+		version: 1,
+		source: CACHE_STACK_ACTIVATION_ENTRY_TYPE,
+		toolNames: value.activatedTools,
+		catalogHash: value.catalogHash,
+	});
+}
+
+/** Read only the latest valid cache-stack activation snapshot on this branch. */
+export function getLatestDeferredToolCarryover(
+	entries: readonly SessionEntry[],
+): DeferredToolCarryoverV1 | undefined {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index];
+		if (entry?.type !== "custom" || entry.customType !== CACHE_STACK_ACTIVATION_ENTRY_TYPE) {
+			continue;
+		}
+
+		const decoded = decodeCacheStackActivationState(entry.data);
+		if (decoded) return decoded;
+	}
+
+	return undefined;
+}
+
+export function isNativeCompactionDetails(value: unknown): value is NativeCompactionDetails {
+	if (!isRecord(value) || !isNativeCompactionIdentity(value)) {
+		return false;
+	}
+
+	const candidate = value as Record<string, unknown>;
+	return (
+		(candidate.strategy === LEGACY_NATIVE_COMPACTION_STRATEGY ||
+			candidate.strategy === REMOTE_V2_COMPACTION_STRATEGY) &&
+		(candidate.inputProvenance === undefined || isNativeCompactionInputProvenance(candidate.inputProvenance)) &&
+		(candidate.compactionModel === undefined || isNativeCompactionIdentity(candidate.compactionModel)) &&
+		(candidate.deferredToolCarryover === undefined || isDeferredToolCarryover(candidate.deferredToolCarryover)) &&
+		Array.isArray(candidate.compactedWindow) &&
+		candidate.compactedWindow.every(isCompactedWindowItem) &&
+		isNonEmptyString(candidate.createdAt) &&
+		(candidate.compactResponseId === undefined || isNonEmptyString(candidate.compactResponseId)) &&
+		(candidate.requestMeta === undefined || isNativeCompactionRequestMeta(candidate.requestMeta))
+	);
+}
+
+export function isNativeCompactionEntry(value: unknown): value is NativeCompactionEntry {
+	return isRecord(value) && value.type === "compaction" && isNativeCompactionDetails(value.details);
+}
+
+export function createNativeCompactionDetails(input: CreateNativeCompactionDetailsInput): NativeCompactionDetails {
+	if (input.strategy !== undefined && input.strategy !== LEGACY_NATIVE_COMPACTION_STRATEGY && input.strategy !== REMOTE_V2_COMPACTION_STRATEGY) {
+		throw new Error("Invalid native compaction strategy");
+	}
+	return {
+		strategy: input.strategy ?? NATIVE_COMPACTION_STRATEGY,
+		inputProvenance: input.inputProvenance,
+		provider: normalizeString(input.provider),
+		api: normalizeString(input.api),
+		model: normalizeString(input.model),
+		baseUrl: normalizeString(input.baseUrl),
+		compactionModel: input.compactionModel
+			? {
+				provider: normalizeString(input.compactionModel.provider),
+				api: normalizeString(input.compactionModel.api),
+				model: normalizeString(input.compactionModel.model),
+				baseUrl: normalizeString(input.compactionModel.baseUrl),
+			}
+			: undefined,
+		deferredToolCarryover: input.deferredToolCarryover
+			? normalizeDeferredToolCarryover(input.deferredToolCarryover)
+			: undefined,
+		compactedWindow: input.compactedWindow.map((item) => cloneStructuredValue(item)),
+		compactResponseId: isNonEmptyString(input.compactResponseId) ? normalizeString(input.compactResponseId) : undefined,
+		createdAt: isNonEmptyString(input.createdAt) ? normalizeString(input.createdAt) : new Date().toISOString(),
+		requestMeta: input.requestMeta
+			? {
+				...(input.requestMeta.tokensBefore !== undefined ? { tokensBefore: input.requestMeta.tokensBefore } : {}),
+				...(input.requestMeta.previousSummaryPresent !== undefined
+					? { previousSummaryPresent: input.requestMeta.previousSummaryPresent }
+					: {}),
+			}
+			: undefined,
+	};
+}
+
+export function createNativeCompactionResult(
+	input: CreateNativeCompactionResultInput,
+): CompactionResult<NativeCompactionDetails> {
+	const summary = input.summary?.trim();
+	return {
+		summary: summary && summary.length > 0 ? summary
+			: input.details.strategy === LEGACY_NATIVE_COMPACTION_STRATEGY ? STANDALONE_COMPACTION_FALLBACK_SUMMARY
+			: NATIVE_COMPACTION_FALLBACK_SUMMARY,
+		firstKeptEntryId: input.firstKeptEntryId,
+		tokensBefore: input.tokensBefore,
+		details: input.details,
+	};
+}
+
+export const DEFAULT_NATIVE_FALLBACK_CONFIG: NativeFallbackConfig = {
+	enabled: true,
+	model: undefined,
+	thinkingLevel: "off",
+};
+
+export const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
+	enabled: true,
+	allowCompactionContinuityBreak: false,
+	remoteCompactModel: undefined,
+	remoteV2ContextSource: "legacy",
+
+	nativeFallback: { ...DEFAULT_NATIVE_FALLBACK_CONFIG },
+	responsesApis: [...RESPONSES_COMPACT_CAPABLE_APIS],
+	gatewayContextModels: [],
+	notifyOnLoad: false,
+	debug: false,
+	logProviderPayloads: false,
+	logCompactResponses: false,
+	redactSensitiveData: true,
+	artifactRoot: DEFAULT_ARTIFACT_ROOT,
+};
+
+export const DEFAULT_WEB_SEARCH_CONFIG: WebSearchConfig = {
+	enabled: true,
+	models: [],
+};
+
+/** Single source of truth for the hosted image model used when nothing is configured. */
+export const DEFAULT_IMAGE_GENERATION_MODEL = "grok-imagine-image-2.0";
+export const DEFAULT_IMAGE_GENERATION_MODELS: readonly string[] = [DEFAULT_IMAGE_GENERATION_MODEL];
+
+export const DEFAULT_IMAGE_GENERATION_CONFIG: ImageGenerationConfig = {
+	enabled: false,
+	models: [...DEFAULT_IMAGE_GENERATION_MODELS],
+};
+
+export const DEFAULT_TOOLKIT_CONFIG: ToolkitConfig = {
+	compaction: DEFAULT_COMPACTION_CONFIG,
+	webSearch: DEFAULT_WEB_SEARCH_CONFIG,
+	imageGeneration: DEFAULT_IMAGE_GENERATION_CONFIG,
+};