pi-openai-toolkit 0.20.2 → 0.20.3

package/docs/internals.md

@@ -45,6 +45,16 @@ Coverage is never inferred from model names. A native session uses provider `ope
 
 ---
 
+### Tool-selection boundary and unavailable Context Management
+
+The four Toolkit context tools are `new_context`, `get_context_remaining`, `history`, and `notes`. The canonical names live in [src/context-management/tool-contract.ts](../src/context-management/tool-contract.ts). A launcher that creates a Pi session for an exact `compaction.gatewayContextModels` model should union those names into an explicit `tools` allowlist before `createAgentSession`, unless the caller selected `noTools`/`--no-tools`; an explicit `excludeTools` entry remains authoritative and is never re-added. This package does not contain the `pi-subagent` or child-session launcher source, so the helper and contract here do not claim to modify that external layer.
+
+After registration, Pi's published registry is authoritative. Toolkit distinguishes `verified` (all four owned definitions), `excluded` (a readable registry contains none of them), `unverified` (a transient read or partial publication), and `conflict` (registration/API/ownership failure). Only `excluded` is a live-turn downgrade: `context_with_system` strips internal window markers, provider payload/header hooks return no-op results, and the lifecycle artifact records `context-tools-excluded`. Conflicts, unreadable/partial registries, malformed window state and missing gateway identity remain fail-closed for live provider requests.
+
+If a covered Remote Context session reaches `session_before_compact` without an active context runtime, the first compaction path is the configured `compaction.remoteCompactModel` through Remote V2. The active session model remains the checkpoint consumer; the configured remote model is only the compactor. If that model is missing/unusable, only an explicitly configured/enabled `nativeFallback.model` may run. Otherwise the hook cancels rather than silently invoking the active model or Pi's default compaction. This compaction fallback does not weaken the live-provider safety rules above.
+
+---
+
 ### Rollover lifecycle
 
 The `new_context` happy path, end to end:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.20.2",
+  "version": "0.20.3",
   "private": false,
   "type": "module",
   "engines": {

package/src/context-management/tool-contract.ts

@@ -13,8 +13,47 @@ export const NOTES_ACTIONS = [
 	"write_file",
 ] as const;
 
+/** Stable names shared by Toolkit registration and an external Pi launcher. */
+export const CONTEXT_MANAGEMENT_TOOL_NAMES = [
+	"new_context",
+	"get_context_remaining",
+	"history",
+	"notes",
+] as const;
+
 export type HistoryAction = (typeof HISTORY_ACTIONS)[number];
 export type NotesAction = (typeof NOTES_ACTIONS)[number];
+export type ContextManagementToolName = (typeof CONTEXT_MANAGEMENT_TOOL_NAMES)[number];
+
+export type ContextToolSelection = {
+	/** Pi's explicit tool allowlist. Omitted means use Pi's default selection. */
+	tools?: readonly string[];
+	/** Pi's default suppression mode. Both values are explicit host policy. */
+	noTools?: "all" | "builtin";
+	/** Pi applies this denylist after the allowlist. */
+	excludeTools?: readonly string[];
+};
+
+/**
+ * Add Toolkit context tools to a host-provided allowlist without overriding an
+ * explicit no-tools or exclude-tools decision. The launcher owns model eligibility;
+ * this helper only owns the shared selection contract.
+ */
+export function ensureContextManagementToolsInAllowlist(
+	selection: ContextToolSelection,
+	eligible: boolean,
+): string[] | undefined {
+	if (!eligible || selection.noTools !== undefined || selection.tools === undefined) {
+		return selection.tools === undefined ? undefined : [...selection.tools];
+	}
+
+	const excluded = new Set(selection.excludeTools ?? []);
+	const names = [...selection.tools];
+	for (const name of CONTEXT_MANAGEMENT_TOOL_NAMES) {
+		if (!excluded.has(name) && !names.includes(name)) names.push(name);
+	}
+	return names;
+}
 
 export const HISTORY_DESCRIPTION =
 	"Prior-window detail. Pass IDs unchanged. Search, never browse.";

package/src/context-management/tools.ts

@@ -223,7 +223,7 @@ export function createContextManagementTools(
 	return { newContext, getContextRemaining, history, notes };
 }
 
-export type ContextToolRegistrationState = "verified" | "conflict" | "unverified";
+export type ContextToolRegistrationState = "verified" | "excluded" | "conflict" | "unverified";
 
 export type ContextToolSyncResult = {
 	synced: boolean;
@@ -300,6 +300,7 @@ export class ContextManagementToolController {
 		const byName = new Map(available.map((tool) => [tool.name, tool]));
 		let missing = false;
 		let conflict = false;
+		let published = 0;
 		for (const name of this.registeredNames) {
 			const actual = byName.get(name);
 			const expected = this.definitions.get(name);
@@ -307,9 +308,13 @@ export class ContextManagementToolController {
 				missing = true;
 				continue;
 			}
+			published += 1;
 			if (!isOurTool(actual, expected)) conflict = true;
 		}
 		if (conflict) return "conflict";
+		// A readable registry with no Toolkit-owned definitions is the positive
+		// host-filtering signal used by --no-tools/restricted child sessions.
+		if (published === 0) return "excluded";
 		if (missing) return "unverified";
 		this.verifiedOnce = true;
 		return "verified";

package/src/extension-runtime.ts

@@ -126,6 +126,7 @@ type RemoteContextActive = (
 	config: CompactionConfig,
 	model?: ExtensionContext["model"],
 ) => Promise<boolean>;
+type ContextToolRegistrationStateReader = () => ContextToolRegistrationState;
 
 type ContextToolSyncOutcome = {
 	eligible: boolean;
@@ -211,6 +212,27 @@ function isCodexContextModel(
 		&& (isNativeCodexModel(model) || isCodexGatewayModel(model, config.gatewayContextModels));
 }
 
+function isExcludedGatewayContext(
+	model: ExtensionContext["model"] | undefined,
+	config: CompactionConfig,
+	registrationState: ContextToolRegistrationState,
+): boolean {
+	return registrationState === "excluded" && isCodexGatewayModel(model, config.gatewayContextModels);
+}
+
+function contextManagementFailureReason(registrationState: ContextToolRegistrationState): string {
+	switch (registrationState) {
+		case "excluded":
+			return "context-tools-excluded";
+		case "conflict":
+			return "tool-name-conflict";
+		case "unverified":
+			return "tool-registration-pending";
+		case "verified":
+			return "context-management-unavailable";
+	}
+}
+
 function notifyRemoteContextFailure(ctx: ExtensionContext, reason: string): void {
 	if (ctx.hasUI) {
 		ctx.ui.notify(`${COMPACTION_EXTENSION_ID}: Remote Context management inactive (${reason})`, "warning");
@@ -567,11 +589,140 @@ async function runResponsesNativeCompact(
 	return { outcome: "success", compaction };
 }
 
+type ContextUnavailableCompactionResult =
+	| { compaction: CompactionResult<unknown> }
+	| { cancel: true };
+
+async function runUnavailableContextCompaction(
+	event: SessionBeforeCompactEvent,
+	ctx: ExtensionContext,
+	dependencies: CompactionDependencies,
+	resolved: ResolvedToolkitConfig,
+	config: CompactionConfig,
+	registrationState: ContextToolRegistrationState,
+): Promise<ContextUnavailableCompactionResult> {
+	const contextReason = contextManagementFailureReason(registrationState);
+	const remoteModelSpec = config.remoteCompactModel?.trim();
+	let remoteFailure: string | undefined;
+
+	if (remoteModelSpec) {
+		const resolution = await resolveRemoteCompactionExecution(
+			ctx,
+			{
+				enabled: config.enabled,
+				responsesApis: config.responsesApis,
+				codexGatewayModels: compactGatewayModels(resolved),
+			},
+			remoteModelSpec,
+		);
+		if (resolution.ok) {
+			const outcome = await runResponsesNativeCompact(
+				event,
+				ctx,
+				config,
+				resolution.execution,
+				dependencies.remoteCompact,
+				dependencies.projectCompactionContext,
+			);
+			if (outcome.outcome === "success") {
+				writeDebugArtifact(
+					"compaction-event",
+					{
+						event: "session_before_compact.context-fallback-success",
+						contextReason,
+						registrationState,
+						compactor: remoteModelSpec,
+					},
+					config,
+					ctx,
+				);
+				return { compaction: outcome.compaction };
+			}
+			if (outcome.outcome === "aborted" || outcome.outcome === "unprojected-input") {
+				return { cancel: true };
+			}
+			remoteFailure = "remote-v2-failed";
+		} else {
+			remoteFailure = resolution.reason;
+			writeDebugArtifact(
+				"compaction-event",
+				{
+					event: "session_before_compact.context-fallback-unavailable",
+					contextReason,
+					registrationState,
+					reason: resolution.reason,
+					modelSpec: remoteModelSpec,
+					errorMessage: resolution.errorMessage,
+				},
+				config,
+				ctx,
+			);
+		}
+	} else {
+		remoteFailure = "missing-remote-compaction-model";
+	}
+
+	const nativeModelSpec = config.nativeFallback.model?.trim();
+	if (config.nativeFallback.enabled && nativeModelSpec) {
+		const fallback = await dependencies.nativeFallback({
+			ctx,
+			event,
+			config,
+			modelSpec: nativeModelSpec,
+		});
+		if (fallback.ok) {
+			writeDebugArtifact(
+				"compaction-event",
+				{
+					event: "session_before_compact.context-fallback-native-success",
+					contextReason,
+					registrationState,
+					remoteFailure,
+					fallbackModel: nativeModelSpec,
+				},
+				config,
+				ctx,
+			);
+			return { compaction: fallback.result };
+		}
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.context-fallback-native-failure",
+				contextReason,
+				registrationState,
+				remoteFailure,
+				fallbackReason: fallback.reason,
+				fallbackModel: nativeModelSpec,
+				errorMessage: fallback.errorMessage,
+			},
+			config,
+			ctx,
+		);
+	} else {
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.context-fallback-cancelled",
+				contextReason,
+				registrationState,
+				remoteFailure,
+				reason: config.nativeFallback.enabled ? "missing-native-fallback-model" : "native-fallback-disabled",
+			},
+			config,
+			ctx,
+		);
+	}
+
+	return { cancel: true };
+}
+
 async function handleSessionBeforeCompact(
 	event: SessionBeforeCompactEvent,
 	ctx: ExtensionContext,
 	dependencies: CompactionDependencies,
 	remoteContextActive: RemoteContextActive,
+	getContextToolRegistrationState: ContextToolRegistrationStateReader,
 ) {
 	const resolved = contextOperation(dependencies.loadConfig, ctx);
 	if (resolved.invalidFeatures.some((feature) => ["context", "compatibility", "diagnostics"].includes(feature))) return { cancel: true };
@@ -602,7 +753,8 @@ async function handleSessionBeforeCompact(
 	}
 
 	// Remote Context management owns this eligible Codex session. It persists a
-	// no-summary boundary and deliberately never calls remote_compaction_v2.
+	// no-summary boundary while active; an unavailable runtime uses the configured
+	// Remote V2 compactor instead of silently returning to Pi's active-model path.
 	const contextModel = await resolveContextCapabilityModel(ctx);
 	if (isCodexContextModel(contextModel, config)) {
 		if (await remoteContextActive(ctx, config, contextModel)) {
@@ -618,14 +770,20 @@ async function handleSessionBeforeCompact(
 				return { cancel: true };
 			}
 		}
-		// A configured native Codex Remote session must never re-enter this
-		// extension's Remote V2 compaction chain, and Pi's native compaction is
-		// deliberately disabled for Remote-managed models: cancelling here keeps
-		// the boundary the only rollover mechanism. The inactive reason is
-		// surfaced so the user can fix activation instead of losing context to a
-		// silent native summary.
-		notifyRemoteContextFailure(ctx, "native-codex-context-unavailable");
-		return { cancel: true };
+
+		const registrationState = getContextToolRegistrationState();
+		const failureReason = contextManagementFailureReason(registrationState);
+		if (failureReason !== "context-tools-excluded") {
+			notifyRemoteContextFailure(ctx, failureReason);
+		}
+		return runUnavailableContextCompaction(
+			event,
+			ctx,
+			dependencies,
+			resolved,
+			config,
+			registrationState,
+		);
 	}
 
 	// Resolve producer protocol policy from this operation's document, not a later disk read.
@@ -865,6 +1023,7 @@ async function handleContextInternal(
 	loadConfig: typeof loadToolkitConfig,
 	contextWindows: CodexContextWindowManager,
 	remoteContextActive: RemoteContextActive,
+	getContextToolRegistrationState: ContextToolRegistrationStateReader,
 ) {
 	const resolved = contextOperation(loadConfig, ctx);
 	requireContextPolicy(resolved, ctx);
@@ -913,13 +1072,21 @@ async function handleContextInternal(
 		}
 
 		// An eligible Codex Remote session is never allowed to fall through to the
-		// older compaction-replay path. Gateway traffic must also fail closed when
-		// its transport capability is unavailable; otherwise Pi could send an
-		// ordinary unscoped request and lose CPA OAuth/session affinity.
+		// older compaction-replay path. An explicit host exclusion is the one
+		// intentional downgrade: strip internal markers and let the ordinary request
+		// proceed without Remote Context affinity.
 		if (isCodexContextModel(contextModel, config)) {
+			const registrationState = getContextToolRegistrationState();
+			if (isExcludedGatewayContext(contextModel, config, registrationState)) {
+				const visibleMessages = contextWindows.project(event.messages, "off");
+				return visibleMessages.length === event.messages.length && visibleMessages.every((message, index) => message === event.messages[index])
+					? undefined
+					: { messages: visibleMessages };
+			}
 			if (isCodexGatewayModel(contextModel, config.gatewayContextModels)) {
-				notifyRemoteContextFailure(ctx, "codex-context-unavailable");
-				reportPiContextHookFailure(ctx, "codex-context-unavailable");
+				const reason = contextManagementFailureReason(registrationState);
+				notifyRemoteContextFailure(ctx, reason);
+				reportPiContextHookFailure(ctx, reason);
 				ctx.abort();
 				return undefined;
 			}
@@ -972,9 +1139,10 @@ async function handleContext(
 	loadConfig: typeof loadToolkitConfig,
 	contextWindows: CodexContextWindowManager,
 	remoteContextActive: RemoteContextActive,
+	getContextToolRegistrationState: ContextToolRegistrationStateReader,
 ) {
 	try {
-		return await handleContextInternal(event, ctx, pi, loadConfig, contextWindows, remoteContextActive);
+		return await handleContextInternal(event, ctx, pi, loadConfig, contextWindows, remoteContextActive, getContextToolRegistrationState);
 	} catch (error) {
 		reportPiContextHookFailure(ctx, error instanceof Error ? error.message : String(error));
 		throw error;
@@ -987,6 +1155,7 @@ async function handleBeforeProviderRequest(
 	loadConfig: typeof loadToolkitConfig,
 	contextWindows: CodexContextWindowManager,
 	remoteContextActive: RemoteContextActive,
+	getContextToolRegistrationState: ContextToolRegistrationStateReader,
 ) {
 	const resolved = contextOperation(loadConfig, ctx);
 	requireContextPolicy(resolved, ctx);
@@ -1018,12 +1187,17 @@ async function handleBeforeProviderRequest(
 		}
 	}
 	if (isCodexContextModel(contextModel, config)) {
+		const registrationState = getContextToolRegistrationState();
+		// A readable empty registry is an intentional host exclusion. Do not
+		// rewrite gateway identity or abort an ordinary child-session request.
+		if (isExcludedGatewayContext(contextModel, config, registrationState)) return undefined;
 		// Keep Codex Remote mutually exclusive with the legacy replay pipeline
 		// when authentication or tool ownership is unavailable. Gateway traffic
 		// cannot continue as an ordinary Responses request because that would
 		// silently lose the required CPA session/account selection.
 		if (isCodexGatewayModel(contextModel, config.gatewayContextModels)) {
-			notifyRemoteContextFailure(ctx, "codex-context-unavailable");
+			const reason = contextManagementFailureReason(registrationState);
+			notifyRemoteContextFailure(ctx, reason);
 			ctx.abort();
 		}
 		return undefined;
@@ -1278,7 +1452,9 @@ export default function registerCompactionExtension(
 		// Only models the built-in Remote Context coverage targets may activate or
 		// warn; everything else silently runs Pi's normal compaction path.
 		if (config.contextManagement === "remote" && isCodexContextModel(contextModel, config) && !active) {
-			if (syncOutcome.registrationState === "conflict") {
+			if (syncOutcome.registrationState === "excluded") {
+				activationReason = "context-tools-excluded";
+			} else if (syncOutcome.registrationState === "conflict") {
 				activationReason = "tool-name-conflict";
 				notifyRemoteContextFailure(ctx, activationReason);
 			} else if (syncOutcome.registrationState === "unverified" || !syncOutcome.toolsSynced) {
@@ -1325,11 +1501,12 @@ export default function registerCompactionExtension(
 		}
 	});
 
+	const getContextToolRegistrationState: ContextToolRegistrationStateReader = () => tools.registrationState;
 	pi.on("context_with_system", (event, ctx) => {
 		manualCompact.guardRequest(ctx);
-		return handleContext(event, ctx, pi, dependencies.loadConfig, contextWindows, remoteContextActive);
+		return handleContext(event, ctx, pi, dependencies.loadConfig, contextWindows, remoteContextActive, getContextToolRegistrationState);
 	});
-	pi.on("session_before_compact", (event, ctx) => handleSessionBeforeCompact(event, ctx, dependencies, remoteContextActive));
+	pi.on("session_before_compact", (event, ctx) => handleSessionBeforeCompact(event, ctx, dependencies, remoteContextActive, getContextToolRegistrationState));
 	pi.on("session_compact", (event, _ctx) => contextWindows.recordCompaction(event.compactionEntry.details));
 	pi.on("session_compact_failed", async (event, ctx) => {
 		if (event.reason === "manual" && !manualCompact.isMaintenance) await manualCompact.compactFailed(ctx);
@@ -1373,7 +1550,7 @@ export default function registerCompactionExtension(
 	});
 	pi.on("before_provider_request", (event, ctx) => {
 		manualCompact.guardRequest(ctx);
-		return handleBeforeProviderRequest(event, ctx, dependencies.loadConfig, contextWindows, remoteContextActive);
+		return handleBeforeProviderRequest(event, ctx, dependencies.loadConfig, contextWindows, remoteContextActive, getContextToolRegistrationState);
 	});
 	pi.on("before_provider_headers", async (event, ctx) => {
 		const resolved = contextOperation(dependencies.loadConfig, ctx);
@@ -1383,8 +1560,11 @@ export default function registerCompactionExtension(
 		if (!isCodexContextModel(contextModel, config)) return;
 		const active = await remoteContextActive(ctx, config, contextModel);
 		if (!active) {
+			const registrationState = getContextToolRegistrationState();
+			if (isExcludedGatewayContext(contextModel, config, registrationState)) return;
 			if (isCodexGatewayModel(contextModel, config.gatewayContextModels)) {
-				notifyRemoteContextFailure(ctx, "codex-context-unavailable");
+				const reason = contextManagementFailureReason(registrationState);
+				notifyRemoteContextFailure(ctx, reason);
 				ctx.abort();
 			}
 			return;