@gajae-code/coding-agent 0.3.2 → 0.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.3.2",
+	"version": "0.4.1",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -36,6 +36,8 @@
 		"check:types": "tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"test": "bun test",
+		"generate-schemas": "bun ../../scripts/generate-json-schemas.ts",
+		"check:schemas": "bun ../../scripts/generate-json-schemas.ts --check",
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index",
 		"fmt": "biome format --write . && bun run format-prompts",
 		"format-prompts": "bun scripts/format-prompts.ts",
@@ -48,12 +50,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.3.2",
-		"@gajae-code/agent-core": "0.3.2",
-		"@gajae-code/ai": "0.3.2",
-		"@gajae-code/natives": "0.3.2",
-		"@gajae-code/tui": "0.3.2",
-		"@gajae-code/utils": "0.3.2",
+		"@gajae-code/stats": "0.4.1",
+		"@gajae-code/agent-core": "0.4.1",
+		"@gajae-code/ai": "0.4.1",
+		"@gajae-code/natives": "0.4.1",
+		"@gajae-code/tui": "0.4.1",
+		"@gajae-code/utils": "0.4.1",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/cli.ts

@@ -84,6 +84,20 @@ function isSubcommand(first: string | undefined): boolean {
 async function runSmokeTest(): Promise<void> {
 	const { smokeTestSyncWorker } = await import("@gajae-code/stats");
 	await smokeTestSyncWorker();
+	// Prove the embedded native addon extracts and the new perf exports resolve in
+	// the COMPILED single binary (dev runs only load the on-disk .node). Loading the
+	// natives module triggers loadNative()/embedded extraction; calling each new
+	// export confirms the symbols are present in the shipped binary.
+	const { h06FormatHashLines, h02ScoreSequenceFuzzy, h01FindBestFuzzyMatch } = await import(
+		"../../natives/native/index.js"
+	);
+	const hashed = h06FormatHashLines("a\nb", 1);
+	if (hashed.split("\n").length !== 2) {
+		throw new Error(`smoke-test: h06FormatHashLines returned unexpected output: ${JSON.stringify(hashed)}`);
+	}
+	if (typeof h02ScoreSequenceFuzzy !== "function" || typeof h01FindBestFuzzyMatch !== "function") {
+		throw new Error("smoke-test: native fuzzy exports missing from embedded addon");
+	}
 	process.stdout.write("smoke-test: ok\n");
 }
 

package/src/commands/harness.ts

@@ -9,20 +9,28 @@
  * until the RuntimeOwner (M3+) lands.
  */
 import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import { Args, Command, Flags } from "@gajae-code/utils/cli";
 import { resolveGjcTmuxCommand, sanitizeTmuxToken } from "../gjc-runtime/tmux-common";
 import { classifyRecovery } from "../harness-control-plane/classifier";
 import { callEndpoint, EndpointUnreachableError } from "../harness-control-plane/control-endpoint";
-import { RuntimeOwner, resolveOwner } from "../harness-control-plane/owner";
+import { type ResolvedOwner, RuntimeOwner, resolveOwner } from "../harness-control-plane/owner";
+import { preserveDirtyWorktree } from "../harness-control-plane/preserve";
+import { buildReceipt, requiresVanishBeforeAction, type VanishEvidence } from "../harness-control-plane/receipts";
 import { GajaeCodeRpc } from "../harness-control-plane/rpc-adapter";
+import { classifyLeaseStatus, readLease } from "../harness-control-plane/session-lease";
 import { buildResponse, buildStateView } from "../harness-control-plane/state-machine";
 import {
+	canonicalWorkspacePath,
 	generateSessionId,
 	readEvents,
 	readSessionState,
+	rememberHarnessSessionRoot,
 	resolveHarnessRoot,
+	resolveHarnessSessionRoot,
 	sessionPaths,
+	writeReceiptImmutable,
 	writeSessionState,
 } from "../harness-control-plane/storage";
 import {
@@ -31,6 +39,7 @@ import {
 	type GitDelta,
 	type Harness as HarnessKind,
 	type Observation,
+	type RecoveryClassification,
 	type RetryBudget,
 	SESSION_SCHEMA_VERSION,
 	type SessionHandle,
@@ -120,8 +129,12 @@ function gitOutput(workspace: string, args: string[]): string | null {
 	}
 }
 
+function resolveInputWorkspace(input: Record<string, unknown>): string {
+	return canonicalWorkspacePath(typeof input.workspace === "string" ? input.workspace : process.cwd());
+}
+
 function buildPreflight(input: Record<string, unknown>): HarnessPreflight {
-	const workspace = typeof input.workspace === "string" ? input.workspace : process.cwd();
+	const workspace = resolveInputWorkspace(input);
 	const declaredBranch = typeof input.branch === "string" && input.branch.trim() ? input.branch.trim() : null;
 	const blockers: string[] = [];
 	const gitRoot = gitOutput(workspace, ["rev-parse", "--show-toplevel"]);
@@ -198,6 +211,7 @@ async function buildObservation(
 	const observedSignals = ["SessionStart"];
 	for (const event of events.slice(-200)) {
 		pushUnique(observedSignals, (event.evidence as { signal?: unknown } | undefined)?.signal);
+		if (event.kind === "prompt_accepted") pushUnique(observedSignals, "prompt-accepted");
 	}
 	const terminalEvent = completedTerminalEvent(events);
 	const lastEventAt = events.at(-1)?.createdAt;
@@ -215,6 +229,114 @@ async function buildObservation(
 		completedTerminalEvent: terminalEvent,
 	};
 }
+interface OwnerExitEvidence {
+	reason: string;
+	leaseStatus: string;
+	pid: number | null;
+	endpointPresent: boolean;
+	heartbeatAt: string | null;
+	expiresAt: string | null;
+	lastEventKind: string | null;
+	lastEventAt: string | null;
+	lastSignal: string | null;
+	promptAcceptedSeen: boolean;
+	completedSeen: boolean;
+}
+
+async function buildOwnerExitEvidence(root: string, state: SessionState): Promise<OwnerExitEvidence> {
+	const lease = await readLease(root, state.sessionId);
+	const leaseStatus = classifyLeaseStatus(lease);
+	const events = await readEvents(root, state.sessionId, 0);
+	const lastEvent = events.at(-1) ?? null;
+	let lastSignal: string | null = null;
+	let promptAcceptedSeen = false;
+	let completedSeen = false;
+	for (const event of events) {
+		const signal = (event.evidence as { signal?: unknown } | undefined)?.signal;
+		if (typeof signal === "string") lastSignal = signal;
+		if (event.kind === "prompt_accepted" || signal === "prompt-accepted") promptAcceptedSeen = true;
+		if (event.kind === "rpc_agent_completed" || signal === "completed") completedSeen = true;
+	}
+	let reason = "owner-not-live";
+	if (!lease) {
+		reason = promptAcceptedSeen && !completedSeen ? "owner-exited-after-prompt-acceptance" : "owner-lease-missing";
+	} else if (leaseStatus === "dead") {
+		reason = promptAcceptedSeen && !completedSeen ? "owner-exited-after-prompt-acceptance" : "owner-process-dead";
+	} else if (leaseStatus === "expiredAlive") {
+		reason = "owner-lease-expired";
+	} else if (leaseStatus === "epermAlive") {
+		reason = "owner-liveness-unknown-permission-denied";
+	} else {
+		reason = "owner-endpoint-unreachable";
+	}
+	return {
+		reason,
+		leaseStatus,
+		pid: lease?.pid ?? null,
+		endpointPresent: Boolean(lease?.endpoint?.path),
+		heartbeatAt: lease?.heartbeatAt ?? null,
+		expiresAt: lease?.expiresAt ?? null,
+		lastEventKind: lastEvent?.kind ?? null,
+		lastEventAt: lastEvent?.createdAt ?? null,
+		lastSignal,
+		promptAcceptedSeen,
+		completedSeen,
+	};
+}
+
+async function writeVanishReceiptForDecision(
+	root: string,
+	state: SessionState,
+	observation: Observation,
+	classification: RecoveryClassification,
+): Promise<string | null> {
+	if (!requiresVanishBeforeAction(classification)) return null;
+	const dirty = observation.gitDelta === "dirty" || observation.gitDelta === "unknown";
+	const preservation = dirty ? preserveDirtyWorktree(observation.cwd) : null;
+	const evidence: VanishEvidence = {
+		classification,
+		gitDelta: observation.gitDelta,
+		gitStatusPorcelain: preservation
+			? `tracked:${preservation.trackedDiffSha256};untracked:${preservation.untrackedManifest.length}`
+			: observation.observedSignals.join(","),
+		untrackedManifest: preservation?.untrackedManifest ?? [],
+		preservation: preservation?.stashRef ? "stash" : "snapshot",
+		stashRef: preservation?.stashRef ?? null,
+		snapshotComplete: preservation?.snapshotComplete ?? true,
+		forbiddenActions: dirty ? ["restart-clean", "delete", "reset"] : [],
+	};
+	const receipt = buildReceipt<VanishEvidence>({
+		receiptId: `vanish-${Date.now()}-${randomBytes(4).toString("hex")}`,
+		sessionId: state.sessionId,
+		family: "vanish",
+		source: "cli-recover",
+		subject: {
+			workspace: observation.cwd,
+			branch: observation.branch,
+			head: null,
+			commit: null,
+		},
+		evidence,
+	});
+	await writeReceiptImmutable(root, state.sessionId, "vanish", receipt.receiptId, receipt);
+	return receipt.receiptId;
+}
+
+function updateStateWithRestoredOwner(state: SessionState, leasePath: string, resolved: ResolvedOwner): void {
+	state.lifecycle = "observing";
+	state.blockers = state.blockers.filter(blocker => !isOwnerLivenessBlocker(blocker));
+	state.handle.processHandle = {
+		kind: "runtime-owner",
+		ownerId: resolved.lease?.ownerId ?? null,
+		pid: resolved.lease?.pid ?? null,
+	};
+	state.handle.ownerHandle = {
+		leasePath,
+		endpoint: resolved.socketPath,
+		heartbeatAt: resolved.lease?.heartbeatAt ?? null,
+	};
+	state.updatedAt = nowIso();
+}
 
 function isOwnerLivenessBlocker(blocker: string): boolean {
 	return blocker === "detached-owner-not-live" || blocker.startsWith("owner-vanished:");
@@ -327,9 +449,14 @@ export default class Harness extends Command {
 	async run(): Promise<void> {
 		const { args, flags } = await this.parse(Harness);
 		const verb = String(args.verb);
-		const root = resolveHarnessRoot();
+		let root = resolveHarnessRoot();
 		try {
 			const input = parseInput(flags.input);
+			const sessionId = flags.session ?? (typeof input.sessionId === "string" ? input.sessionId : undefined);
+			const expectedWorkspace = typeof input.workspace === "string" ? resolveInputWorkspace(input) : undefined;
+			if (verb !== "start" && sessionId) {
+				root = await resolveHarnessSessionRoot(root, sessionId, process.env, { expectedWorkspace });
+			}
 			switch (verb) {
 				case "start":
 					return await this.#start(root, input);
@@ -468,6 +595,9 @@ export default class Harness extends Command {
 		if (process.env.GJC_HARNESS_RPC_COMMAND) {
 			envAssignments.push(`GJC_HARNESS_RPC_COMMAND=${shellQuote(process.env.GJC_HARNESS_RPC_COMMAND)}`);
 		}
+		if (process.env.GJC_HARNESS_TEST_NODE_MODULES) {
+			envAssignments.push(`GJC_HARNESS_TEST_NODE_MODULES=${shellQuote(process.env.GJC_HARNESS_TEST_NODE_MODULES)}`);
+		}
 		const ownerCommand = this.#buildOwnerCommand(sessionId).map(shellQuote).join(" ");
 		const shellCommand = `exec env ${envAssignments.join(" ")} ${ownerCommand}`;
 		const created = Bun.spawnSync([tmuxCommand, "new-session", "-d", "-s", sessionName, "-c", cwd, shellCommand], {
@@ -498,7 +628,13 @@ export default class Harness extends Command {
 		const cmd = this.#buildOwnerCommand(sessionId);
 		const child = Bun.spawn(cmd, {
 			cwd,
-			env: { ...process.env, GJC_HARNESS_STATE_ROOT: root },
+			env: {
+				...process.env,
+				GJC_HARNESS_STATE_ROOT: root,
+				...(process.env.GJC_HARNESS_TEST_NODE_MODULES
+					? { GJC_HARNESS_TEST_NODE_MODULES: process.env.GJC_HARNESS_TEST_NODE_MODULES }
+					: {}),
+			},
 			stdout: "ignore",
 			stderr: "ignore",
 			stdin: "ignore",
@@ -540,7 +676,7 @@ export default class Harness extends Command {
 			process.exitCode = 1;
 			return;
 		}
-		const workspace = typeof input.workspace === "string" ? input.workspace : process.cwd();
+		const workspace = resolveInputWorkspace(input);
 		const sessionId = typeof input.sessionId === "string" ? input.sessionId : generateSessionId();
 		const eventsPath = `${root}/sessions/${sessionId}/events.jsonl`;
 		const leasePath = `${root}/sessions/${sessionId}/lease.json`;
@@ -573,6 +709,7 @@ export default class Harness extends Command {
 			updatedAt: startedAt,
 		};
 		await writeSessionState(root, state);
+		await rememberHarnessSessionRoot(root, sessionId);
 		let ownerLive = false;
 		let ownerRuntime: OwnerSpawnResult["runtime"] = "manual";
 		let ownerFallbackReason: string | null = null;
@@ -676,6 +813,10 @@ export default class Harness extends Command {
 		state = await reconcileCompletedOwnerExited(root, state, observation, completedTerminalEvent);
 		const vanishedOwnerBlock = needsVanishedOwnerBlock(state, observation, completedTerminalEvent);
 		state = await markVanishedOwnerBlocked(root, state, observation, completedTerminalEvent);
+		const ownerExit =
+			!ownerLive && (vanishedOwnerBlock || completedTerminalEvent)
+				? await buildOwnerExitEvidence(root, state)
+				: null;
 		writeJson(
 			buildResponse(state, ownerLive, {
 				observation: { ...observation, lifecycle: state.lifecycle },
@@ -686,6 +827,7 @@ export default class Harness extends Command {
 				...(completedTerminalEvent && !ownerLive
 					? { completedOwnerExited: true, terminalResult: completedTerminalEvent }
 					: {}),
+				...(ownerExit ? { ownerExit } : {}),
 			}),
 		);
 	}
@@ -767,7 +909,9 @@ export default class Harness extends Command {
 			buildResponse(state, ownerLiveFor(state), {
 				events,
 				cursor: nextCursor,
-				note: "tail-only; live producer (owner) lands in M3/M5",
+				note: "tail-only; events are preserved after owner exit",
+				ownerLive: ownerLiveFor(state),
+				ownerExit: ownerLiveFor(state) ? null : await buildOwnerExitEvidence(root, state),
 			}),
 		);
 	}
@@ -802,21 +946,62 @@ export default class Harness extends Command {
 	async #recoverWithoutOwner(root: string, sessionId: string, input: Record<string, unknown>): Promise<void> {
 		const budget = resolveRetryBudget(input);
 		let state = await loadState(root, sessionId);
+		const beforeExit = await buildOwnerExitEvidence(root, state);
 		const { observation, completedTerminalEvent } = await buildObservation(root, state, false);
 		state = await markVanishedOwnerBlocked(root, state, observation, completedTerminalEvent);
 		const decision = classifyRecovery({
 			observation: { ...observation, lifecycle: state.lifecycle },
 			retryBudget: budget,
 		});
+		const vanishReceiptId = await writeVanishReceiptForDecision(root, state, observation, decision.classification);
+		const restoredOwner =
+			decision.ownerRequired && beforeExit.endpointPresent
+				? await this.#spawnDetachedOwner(root, sessionId, state.handle.workspace)
+				: null;
+		if (restoredOwner?.live) {
+			const resolved = await resolveOwner(root, sessionId);
+			if (resolved.live && resolved.socketPath) {
+				updateStateWithRestoredOwner(state, state.handle.ownerHandle.leasePath, resolved);
+				if (restoredOwner.tmuxSessionName)
+					state.handle.viewportHandle.tmuxSessionName = restoredOwner.tmuxSessionName;
+				await writeSessionState(root, state);
+				writeJson(
+					buildResponse(state, true, {
+						pending: false,
+						restoredOwner: true,
+						decision,
+						observation: { ...observation, lifecycle: state.lifecycle, ownerLive: true },
+						ownerExit: beforeExit,
+						ownerRuntime: restoredOwner.runtime,
+						...(restoredOwner.fallbackReason ? { ownerFallbackReason: restoredOwner.fallbackReason } : {}),
+						...(vanishReceiptId ? { vanishReceiptId } : {}),
+					}),
+				);
+				return;
+			}
+		}
+		const afterExit = await buildOwnerExitEvidence(root, state);
 		writeJson(
 			buildResponse(
 				state,
 				false,
 				{
 					pending: false,
-					reason: "owner-not-live",
+					reason: afterExit.reason,
 					decision,
 					observation: { ...observation, lifecycle: state.lifecycle },
+					ownerExit: afterExit,
+					...(restoredOwner
+						? {
+								restoreAttempt: {
+									runtime: restoredOwner.runtime,
+									live: restoredOwner.live,
+									fallbackReason: restoredOwner.fallbackReason,
+									blockerReason: restoredOwner.blockerReason,
+								},
+							}
+						: {}),
+					...(vanishReceiptId ? { vanishReceiptId } : {}),
 				},
 				false,
 			),

package/src/commands/ultragoal.ts

@@ -6,13 +6,7 @@ import {
 	writeCurrentSessionGoalModeState,
 	writePendingGoalModeRequest,
 } from "../gjc-runtime/goal-mode-request";
-import {
-	buildUltragoalHudSummary,
-	getUltragoalStatus,
-	readUltragoalLedger,
-	runNativeUltragoalCommand,
-} from "../gjc-runtime/ultragoal-runtime";
-import { syncSkillActiveState } from "../skill-state/active-state";
+import { runNativeUltragoalCommand } from "../gjc-runtime/ultragoal-runtime";
 
 export default class Ultragoal extends Command {
 	static description = "Run native GJC Ultragoal workflow commands";
@@ -25,20 +19,6 @@ export default class Ultragoal extends Command {
 		if (result.stdout) process.stdout.write(result.stdout);
 		if (result.stderr) process.stderr.write(result.stderr);
 		process.exitCode = result.status;
-		try {
-			const summary = await getUltragoalStatus(process.cwd());
-			const ledger = await readUltragoalLedger(process.cwd());
-			await syncSkillActiveState({
-				cwd: process.cwd(),
-				skill: "ultragoal",
-				active: summary.exists && summary.status !== "complete",
-				phase: summary.status,
-				hud: buildUltragoalHudSummary(summary, ledger.at(-1)),
-				source: "gjc-ultragoal",
-			});
-		} catch {
-			// HUD sync is best-effort and must not change command semantics.
-		}
 		if (result.status !== 0 || !shouldActivateGoalMode) return;
 
 		const cwd = process.cwd();

package/src/config/model-equivalence.ts

@@ -42,7 +42,7 @@ interface ResolvedCanonicalModel {
 }
 
 const TRAILING_MARKER_PATTERN =
-	/[-:](?:thinking|customtools|high|low|medium|minimal|xhigh|free|cloud|exacto|nitro|original|optimized|nvfp4|fp8|fp4|bf16|int8|int4)$/i;
+	/[-:](?:thinking|customtools|high|low|medium|minimal|xhigh|max|free|cloud|exacto|nitro|original|optimized|nvfp4|fp8|fp4|bf16|int8|int4)$/i;
 const WRAPPER_PREFIXES = ["duo-chat-"] as const;
 
 let referenceDataCache: CanonicalReferenceData | undefined;

package/src/config/model-registry.ts

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import {
 	type Api,
 	type AssistantMessageEventStream,
+	type CacheRetention,
 	type Context,
 	createModelManager,
 	enrichModelThinking,
@@ -240,6 +241,7 @@ interface ProviderValidationConfig {
 	compat?: Model<Api>["compat"];
 	requestTransform?: ModelRequestTransform;
 	disableStrictTools?: boolean;
+	cacheRetention?: CacheRetention;
 	modelOverrides?: Record<string, unknown>;
 	models: ProviderValidationModel[];
 }
@@ -267,11 +269,12 @@ function validateProviderConfiguration(
 				!config.apiKeyEnv &&
 				!config.disableStrictTools &&
 				!config.requestTransform &&
+				!config.cacheRetention &&
 				!hasModelOverrides &&
 				!config.discovery
 			) {
 				throw new Error(
-					`Provider ${providerName}: must specify "baseUrl", "headers", "apiKey", "compat", "requestTransform", "disableStrictTools", "modelOverrides", "discovery", or "models"`,
+					`Provider ${providerName}: must specify "baseUrl", "headers", "apiKey", "compat", "requestTransform", "cacheRetention", "disableStrictTools", "modelOverrides", "discovery", or "models"`,
 				);
 			}
 		}
@@ -384,6 +387,7 @@ export const ModelsConfigFile = new ConfigFile<ModelsConfig>("models", ModelsCon
 					compat: providerConfig.compat,
 					requestTransform: providerConfig.requestTransform,
 					disableStrictTools: providerConfig.disableStrictTools,
+					cacheRetention: providerConfig.cacheRetention,
 					modelOverrides: providerConfig.modelOverrides,
 					models: (providerConfig.models ?? []) as ProviderValidationModel[],
 				},
@@ -402,6 +406,7 @@ interface ProviderOverride {
 	compat?: Model<Api>["compat"];
 	transport?: Model<Api>["transport"];
 	requestTransform?: ModelRequestTransform;
+	cacheRetention?: CacheRetention;
 }
 
 const PROVIDER_BASE_URL_ENV_ALIASES: Record<string, readonly string[]> = {
@@ -449,7 +454,10 @@ function resolveProviderBaseUrlFromEnv(provider: string): string | undefined {
 export function mergeDiscoveredModel<TApi extends Api>(
 	model: Model<TApi>,
 	existing: Model<Api> | undefined,
-	providerOverride?: Pick<ProviderOverride, "baseUrl" | "headers" | "transport" | "requestTransform">,
+	providerOverride?: Pick<
+		ProviderOverride,
+		"baseUrl" | "headers" | "transport" | "requestTransform" | "cacheRetention"
+	>,
 ): Model<TApi> {
 	if (existing) {
 		return {
@@ -460,6 +468,7 @@ export function mergeDiscoveredModel<TApi extends Api>(
 				mergeRequestTransform(existing.requestTransform, model.requestTransform),
 				providerOverride?.requestTransform,
 			),
+			cacheRetention: model.cacheRetention ?? existing.cacheRetention ?? providerOverride?.cacheRetention,
 		};
 	}
 	if (providerOverride) {
@@ -481,6 +490,7 @@ interface DiscoveryProviderConfig {
 	headers?: Record<string, string>;
 	compat?: Model<Api>["compat"];
 	requestTransform?: ModelRequestTransform;
+	cacheRetention?: CacheRetention;
 	discovery: ProviderDiscovery;
 	optional?: boolean;
 }
@@ -678,6 +688,7 @@ function applyModelOverride(model: Model<Api>, override: ModelOverride): Model<A
 	if (override.reasoning !== undefined) result.reasoning = override.reasoning;
 	if (override.thinking !== undefined) result.thinking = override.thinking as ThinkingConfig;
 	if (override.input !== undefined) result.input = override.input as ("text" | "image")[];
+	if (override.cacheRetention !== undefined) result.cacheRetention = override.cacheRetention;
 	if (override.contextWindow !== undefined) result.contextWindow = override.contextWindow;
 	if (override.maxTokens !== undefined) result.maxTokens = override.maxTokens;
 	if (override.contextPromotionTarget !== undefined) result.contextPromotionTarget = override.contextPromotionTarget;
@@ -716,6 +727,7 @@ interface CustomModelDefinitionLike {
 	premiumMultiplier?: number;
 	wireModelId?: string;
 	requestTransform?: ModelRequestTransform;
+	cacheRetention?: CacheRetention;
 }
 
 interface CustomModelBuildOptions {
@@ -740,6 +752,7 @@ type CustomModelOverlay = {
 	premiumMultiplier?: number;
 	wireModelId?: string;
 	requestTransform?: ModelRequestTransform;
+	cacheRetention?: CacheRetention;
 	isOAuth?: boolean;
 };
 
@@ -791,6 +804,7 @@ function buildCustomModelOverlay(
 	providerCompat: Model<Api>["compat"] | undefined,
 	providerRequestTransform: ModelRequestTransform | undefined,
 	providerAuth: ProviderAuthMode | undefined,
+	providerCacheRetention: CacheRetention | undefined,
 	modelDef: CustomModelDefinitionLike,
 ): CustomModelOverlay | undefined {
 	const api = modelDef.api ?? providerApi;
@@ -813,6 +827,7 @@ function buildCustomModelOverlay(
 		wireModelId: modelDef.wireModelId,
 		contextPromotionTarget: modelDef.contextPromotionTarget,
 		premiumMultiplier: modelDef.premiumMultiplier,
+		cacheRetention: modelDef.cacheRetention ?? providerCacheRetention,
 		isOAuth: resolveCustomModelIsOAuth(api, providerAuth),
 	};
 }
@@ -913,6 +928,7 @@ function finalizeCustomModel(model: CustomModelOverlay, options: CustomModelBuil
 		contextPromotionTarget: resolvedModel.contextPromotionTarget,
 		wireModelId: resolvedModel.wireModelId,
 		requestTransform: resolvedModel.requestTransform,
+		cacheRetention: resolvedModel.cacheRetention ?? reference?.cacheRetention,
 		premiumMultiplier: resolvedModel.premiumMultiplier,
 		isOAuth: resolvedModel.isOAuth,
 	} as Model<Api>);
@@ -1139,6 +1155,7 @@ export class ModelRegistry {
 				return {
 					...withTransportOverride,
 					compat: mergeCompat(m.compat, providerOverride.compat),
+					cacheRetention: m.cacheRetention ?? providerOverride.cacheRetention,
 				};
 			});
 		});
@@ -1295,6 +1312,7 @@ export class ModelRegistry {
 				requestTransform: providerConfig.requestTransform
 					? mergeRequestTransform(undefined, providerConfig.requestTransform)
 					: undefined,
+				cacheRetention: normalized.cacheRetention ?? providerConfig.cacheRetention,
 			};
 		});
 	}
@@ -1383,7 +1401,8 @@ export class ModelRegistry {
 				providerConfig.compat ||
 				providerConfig.disableStrictTools ||
 				providerConfig.requestTransform ||
-				providerConfig.transport
+				providerConfig.transport ||
+				providerConfig.cacheRetention
 			) {
 				const disableStrictCompat = providerConfig.disableStrictTools ? { disableStrictTools: true } : undefined;
 				overrides.set(providerName, {
@@ -1394,6 +1413,7 @@ export class ModelRegistry {
 					compat: mergeCompat(providerConfig.compat, disableStrictCompat),
 					transport: providerConfig.transport,
 					requestTransform: providerConfig.requestTransform,
+					cacheRetention: providerConfig.cacheRetention,
 				});
 			}
 
@@ -1410,6 +1430,7 @@ export class ModelRegistry {
 					headers: providerConfig.headers,
 					compat: providerConfig.compat,
 					requestTransform: providerConfig.requestTransform,
+					cacheRetention: providerConfig.cacheRetention,
 					discovery: providerConfig.discovery,
 					optional: false,
 				});
@@ -2101,13 +2122,16 @@ export class ModelRegistry {
 			compat: override.compat ? mergeCompat(baseOverride?.compat, override.compat) : baseOverride?.compat,
 			transport: override.transport ?? baseOverride?.transport,
 			requestTransform: mergeRequestTransform(baseOverride?.requestTransform, override.requestTransform),
+			cacheRetention: override.cacheRetention ?? baseOverride?.cacheRetention,
 		};
 	}
-	#applyProviderTransportOverride<T extends { baseUrl?: string; headers?: Record<string, string> }>(
+	#applyProviderTransportOverride<
+		T extends { baseUrl?: string; headers?: Record<string, string>; cacheRetention?: CacheRetention },
+	>(
 		entry: T,
 		override: Pick<
 			ProviderOverride,
-			"baseUrl" | "headers" | "authHeader" | "apiKey" | "transport" | "requestTransform"
+			"baseUrl" | "headers" | "authHeader" | "apiKey" | "transport" | "requestTransform" | "cacheRetention"
 		>,
 	): T {
 		const headers = mergeAuthHeader(
@@ -2126,6 +2150,7 @@ export class ModelRegistry {
 				(entry as { requestTransform?: ModelRequestTransform }).requestTransform,
 				override.requestTransform,
 			),
+			cacheRetention: entry.cacheRetention ?? override.cacheRetention,
 		};
 	}
 	#applyRuntimeProviderOverrides(models: Model<Api>[]): Model<Api>[] {
@@ -2214,6 +2239,7 @@ export class ModelRegistry {
 					providerCompat,
 					providerConfig.requestTransform,
 					(providerConfig.auth as ProviderAuthMode | undefined) ?? undefined,
+					providerConfig.cacheRetention,
 					modelDef as CustomModelDefinitionLike,
 				);
 				if (!model) continue;
@@ -2576,6 +2602,7 @@ export class ModelRegistry {
 					config.compat,
 					config.requestTransform,
 					undefined,
+					undefined,
 					modelDef as CustomModelDefinitionLike,
 				);
 				if (!overlay) {

package/src/config/models-config-schema.ts

@@ -16,6 +16,7 @@ const ReasoningEffortMapSchema = z.object({
 	medium: z.string().optional(),
 	high: z.string().optional(),
 	xhigh: z.string().optional(),
+	max: z.string().optional(),
 });
 
 export const OpenAICompatSchema = z.object({
@@ -45,7 +46,8 @@ export const OpenAICompatSchema = z.object({
 	toolStrictMode: z.enum(["all_strict", "none"]).optional(),
 });
 
-const EffortSchema = z.enum(["minimal", "low", "medium", "high", "xhigh"]);
+const EffortSchema = z.enum(["minimal", "low", "medium", "high", "xhigh", "max"]);
+const CacheRetentionSchema = z.enum(["none", "short", "long"]);
 
 const ThinkingControlModeSchema = z.enum([
 	"effort",
@@ -89,7 +91,7 @@ function isValidProfileModelSelector(value: string): boolean {
 	if (parts.length > 2) return false;
 	const [base, suffix] = parts;
 	if (!base) return false;
-	return suffix === undefined || ["minimal", "low", "medium", "high", "xhigh"].includes(suffix);
+	return suffix === undefined || ["minimal", "low", "medium", "high", "xhigh", "max"].includes(suffix);
 }
 
 export const ProfileModelSelectorSchema = z
@@ -149,6 +151,7 @@ const ModelDefinitionSchema = z
 		contextPromotionTarget: z.string().min(1).optional(),
 		wireModelId: z.string().min(1).optional(),
 		requestTransform: RequestTransformSchema.optional(),
+		cacheRetention: CacheRetentionSchema.optional(),
 	})
 	.strict();
 
@@ -174,6 +177,7 @@ export const ModelOverrideSchema = z
 		contextPromotionTarget: z.string().min(1).optional(),
 		wireModelId: z.string().min(1).optional(),
 		requestTransform: RequestTransformSchema.optional(),
+		cacheRetention: CacheRetentionSchema.optional(),
 	})
 	.strict();
 
@@ -225,6 +229,7 @@ const ProviderConfigSchema = z
 		 * and `apiKey` must carry the gateway bearer.
 		 */
 		transport: z.literal("pi-native").optional(),
+		cacheRetention: CacheRetentionSchema.optional(),
 	})
 	.strict();