pi-openai-toolkit 0.14.10 → 0.14.11

package/package.json

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

package/src/context-management/tools.ts

@@ -12,13 +12,25 @@ import type { HistoryAction, NotesAction } from "./types";
 
 const EMPTY_PARAMETERS = Type.Object({}, { additionalProperties: false });
 
-function arrayEquals(a: readonly string[] | undefined, b: readonly string[] | undefined): boolean {
-	if (a === b) return true;
-	if (!a || !b || a.length !== b.length) return false;
-	for (let i = 0; i < a.length; i++) {
-		if (a[i] !== b[i]) return false;
-	}
-	return true;
+type PublishedTool = {
+	name: string;
+	description: string;
+	parameters: unknown;
+	promptGuidelines?: string[];
+};
+
+/**
+ * Pi's ToolInfo wrapper is new, but its definition fields retain the objects
+ * registered by the extension. Keep identity checks for those fields: an exact
+ * foreign clone under the same name is still not ownership of our tool.
+ */
+function isOurTool(
+	actual: PublishedTool,
+	expected: { description: string; parameters: unknown; promptGuidelines?: string[] },
+): boolean {
+	return actual.description === expected.description
+		&& actual.parameters === expected.parameters
+		&& actual.promptGuidelines === expected.promptGuidelines;
 }
 const HISTORY_ACTIONS = Object.keys(HISTORY_ENDPOINTS) as [HistoryAction, ...HistoryAction[]];
 const NOTES_ACTIONS = Object.keys(NOTES_ENDPOINTS) as [NotesAction, ...NotesAction[]];
@@ -182,6 +194,13 @@ export function createContextManagementTools(
 	return { newContext, getContextRemaining, history, notes };
 }
 
+export type ContextToolRegistrationState = "verified" | "conflict" | "unverified";
+
+export type ContextToolSyncResult = {
+	synced: boolean;
+	registrationState: ContextToolRegistrationState;
+};
+
 export class ContextManagementToolController {
 	private readonly registeredNames = new Set<string>();
 	private readonly definitions = new Map<string, {
@@ -190,8 +209,7 @@ export class ContextManagementToolController {
 		promptGuidelines?: string[];
 	}>();
 	private registered = false;
-	private registrationChecked = false;
-	private registrationValid = false;
+	private verifiedOnce = false;
 
 	constructor(private readonly pi: ExtensionAPI) {}
 
@@ -205,12 +223,16 @@ export class ContextManagementToolController {
 		// those are bound only after extension loading completes.
 		try {
 			for (const definition of definitions) api.registerTool(definition);
+			this.registered = true;
 		} catch {
+			// Pi rejects a registration whose name is already owned elsewhere.
+			this.registered = false;
 			return false;
 		}
 
 		this.registeredNames.clear();
 		this.definitions.clear();
+		this.verifiedOnce = false;
 		for (const definition of definitions) {
 			this.registeredNames.add(definition.name);
 			this.definitions.set(definition.name, {
@@ -219,43 +241,58 @@ export class ContextManagementToolController {
 				promptGuidelines: definition.promptGuidelines,
 			});
 		}
-		this.registered = true;
-		this.registrationChecked = false;
-		this.registrationValid = false;
+		// A successful call only proves the hand-off; it does not prove the runtime
+		// published the definitions. `checkRegistration()` reads that from Pi.
 		return true;
 	}
 
-	private verifyRegistration(): boolean {
-		if (!this.registered) return false;
-		if (this.registrationChecked) return this.registrationValid;
-		this.registrationChecked = true;
+	/**
+	 * Read registration state until the runtime confirms publication.
+	 *
+	 * Pi 0.86 can reject action methods while a session replacement is still
+	 * binding, and can publish the registry after `session_start` ran. Negative
+	 * reads remain retryable; only a successful verification is cached for this
+	 * controller instance. A Pi reload creates a new controller.
+	 */
+	checkRegistration(): ContextToolRegistrationState {
+		if (!this.registered) return "conflict";
+		// A confirmed publication is kept: the expensive part was never the read, it
+		// was trusting a failed one. Only negative verdicts are recomputed each time.
+		if (this.verifiedOnce) return "verified";
+		let available: PublishedTool[];
 		try {
-			const api = this.pi as ExtensionAPI & { getAllTools?: () => Array<{
-				name: string;
-				description: string;
-				parameters: unknown;
-				promptGuidelines?: string[];
-			}> };
-			if (typeof api.getAllTools !== "function") return false;
-			const available = new Map(api.getAllTools().map((tool) => [tool.name, tool]));
-			this.registrationValid = [...this.registeredNames].every((name) => {
-				const actual = available.get(name);
-				const expected = this.definitions.get(name);
-				return actual !== undefined && expected !== undefined &&
-					actual.description === expected.description &&
-					actual.parameters === expected.parameters &&
-					actual.promptGuidelines === expected.promptGuidelines;
-			});
+			const api = this.pi as ExtensionAPI & { getAllTools?: () => PublishedTool[] };
+			if (typeof api.getAllTools !== "function") return "conflict";
+			available = api.getAllTools();
 		} catch {
-			this.registrationValid = false;
+			// Stale or unbound runtime: retry on the next sync.
+			return "unverified";
+		}
+		const byName = new Map(available.map((tool) => [tool.name, tool]));
+		let missing = false;
+		let conflict = false;
+		for (const name of this.registeredNames) {
+			const actual = byName.get(name);
+			const expected = this.definitions.get(name);
+			if (actual === undefined || expected === undefined) {
+				missing = true;
+				continue;
+			}
+			if (!isOurTool(actual, expected)) conflict = true;
 		}
-		return this.registrationValid;
+		if (conflict) return "conflict";
+		if (missing) return "unverified";
+		this.verifiedOnce = true;
+		return "verified";
 	}
 
-	sync(active: boolean): boolean {
-		if (!this.verifyRegistration()) return false;
+	sync(active: boolean): ContextToolSyncResult {
+		const registrationState = this.checkRegistration();
+		if (registrationState !== "verified") return { synced: false, registrationState };
 		const api = this.pi as ExtensionAPI & { getActiveTools?: () => string[]; setActiveTools?: (names: string[]) => void };
-		if (typeof api.getActiveTools !== "function" || typeof api.setActiveTools !== "function") return false;
+		if (typeof api.getActiveTools !== "function" || typeof api.setActiveTools !== "function") {
+			return { synced: false, registrationState };
+		}
 		try {
 			const current = api.getActiveTools();
 			// Pi may activate a newly registered tool before the first sync. Once
@@ -265,16 +302,17 @@ export class ContextManagementToolController {
 				? [...current, ...[...this.registeredNames].filter((name) => !current.includes(name))]
 				: current.filter((name) => !this.registeredNames.has(name));
 			if (next.length !== current.length) api.setActiveTools(next);
-			return true;
+			return { synced: true, registrationState };
 		} catch {
-			return false;
+			return { synced: false, registrationState };
 		}
 	}
 
 	reset(): void {
 		this.sync(false);
 	}
-	get isRegistered(): boolean { return this.registrationValid; }
+	get isRegistered(): boolean { return this.checkRegistration() === "verified"; }
+	get registrationState(): ContextToolRegistrationState { return this.checkRegistration(); }
 }
 
 export function registerContextManagementTools(

package/src/extension-runtime.ts

@@ -17,7 +17,10 @@ import {
 import { routeContextNamespaceToolMessage } from "./context-management/namespace-tools";
 import { loadHistoryNotesThreadHint } from "./context-management/history-notes";
 import { CodexContextWindowManager } from "./context-management/window-manager";
-import { registerContextManagementTools } from "./context-management/tools";
+import {
+	registerContextManagementTools,
+	type ContextToolRegistrationState,
+} from "./context-management/tools";
 import { writeDebugArtifact, writeReplayFailureArtifact } from "./debug";
 import {
 	COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE,
@@ -88,6 +91,13 @@ type RemoteContextActive = (
 	model?: ExtensionContext["model"],
 ) => Promise<boolean>;
 
+type ContextToolSyncOutcome = {
+	eligible: boolean;
+	toolsSynced: boolean;
+	registrationState: ContextToolRegistrationState;
+	windowInitialized: boolean;
+};
+
 type ResponsesCompactOutcome =
 	| { outcome: "success"; compaction: CompactionResult<NativeCompactionDetails> }
 	| { outcome: "aborted" }
@@ -1015,28 +1025,60 @@ export default function registerCompactionExtension(
 		piContextHookPatch: overrides.piContextHookPatch ?? piContextHookPatch,
 	};
 	let tools!: ReturnType<typeof registerContextManagementTools>;
+	let contextWindowReady = false;
+	const isContextRuntimeActive = async (
+		ctx: ExtensionContext,
+		config: CompactionConfig,
+		model = ctx.model,
+	): Promise<boolean> =>
+		contextWindowReady && tools.isRegistered && await isRemoteContextActive(ctx, config, model);
 	tools = registerContextManagementTools(
 		pi,
 		contextWindows,
 		async (ctx) => {
 			const config = dependencies.loadConfig().config.compaction;
-			return tools.isRegistered && await isRemoteContextActive(ctx, config);
+			return isContextRuntimeActive(ctx, config);
 		},
 		() => dependencies.loadConfig().config.compaction.gatewayContextModels,
 	);
-	const remoteContextActive: RemoteContextActive = async (ctx, config, model = ctx.model) =>
-		tools.isRegistered && await isRemoteContextActive(ctx, config, model);
-	const syncTools = async (ctx: ExtensionContext, model = ctx.model): Promise<boolean> => {
+	const remoteContextActive: RemoteContextActive = isContextRuntimeActive;
+	const syncTools = async (
+		ctx: ExtensionContext,
+		model = ctx.model,
+		options: { notifyWindowFailure?: boolean } = {},
+	): Promise<ContextToolSyncOutcome> => {
+		// Until this call proves otherwise, do not let a previous session/window
+		// identity make a failed activation look usable.
+		contextWindowReady = false;
 		const config = dependencies.loadConfig().config.compaction;
-		const active = await isRemoteContextActive(ctx, config, model);
-		// sync() reports whether the tool-set update succeeded; an inactive model
-		// syncs fine and returns true. The activation decision must use `active`
-		// itself, or non-covered models would receive a window boundary.
-		const synced = tools.sync(active);
-		return active && synced;
+		const eligible = await isRemoteContextActive(ctx, config, model);
+		const toolSync = tools.sync(eligible);
+		const outcome: ContextToolSyncOutcome = {
+			eligible,
+			toolsSynced: toolSync.synced,
+			registrationState: toolSync.registrationState,
+			windowInitialized: false,
+		};
+		if (!eligible || !toolSync.synced) return outcome;
+		// Activation can succeed after `session_start` missed it, because Pi 0.86 may
+		// reject the registration read while a session replacement is still binding.
+		// The window lifecycle has to open on that later activation too, or requests
+		// carry no window metadata and the backend never ingests the turns.
+		try {
+			contextWindows.ensureInitialized(pi, ctx, true);
+			contextWindowReady = true;
+			return { ...outcome, windowInitialized: true };
+		} catch {
+			// Do not leave tools exposed while the request path has no valid window
+			// identity. The next lifecycle hook may retry once Pi is usable again.
+			tools.sync(false);
+			if (options.notifyWindowFailure) notifyRemoteContextFailure(ctx, "malformed-window-state");
+			return outcome;
+		}
 	};
 	pi.on("session_start", async (_event, ctx) => {
-		const active = await syncTools(ctx);
+		const syncOutcome = await syncTools(ctx, ctx.model, { notifyWindowFailure: true });
+		const active = syncOutcome.eligible && syncOutcome.toolsSynced && syncOutcome.windowInitialized;
 		const { config: toolkitConfig, source, warnings } = dependencies.loadConfig();
 		const config = toolkitConfig.compaction;
 		if (!config.enabled) return;
@@ -1044,16 +1086,16 @@ export default function registerCompactionExtension(
 		let activationReason: string | undefined;
 		// 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(ctx.model, config)) {
-			if (active) {
-				try {
-					contextWindows.ensureInitialized(pi, ctx, true);
-				} catch {
-					notifyRemoteContextFailure(ctx, "malformed-window-state");
-				}
-			} else if (!tools.isRegistered) {
+		if (config.contextManagement === "remote" && isCodexContextModel(ctx.model, config) && !active) {
+			if (syncOutcome.registrationState === "conflict") {
 				activationReason = "tool-name-conflict";
 				notifyRemoteContextFailure(ctx, activationReason);
+			} else if (syncOutcome.registrationState === "unverified" || !syncOutcome.toolsSynced) {
+				// Transient: the runtime has not published or accepted our tools yet. A
+				// later before_agent_start re-verifies, so do not report provider failure.
+				activationReason = "tool-registration-pending";
+			} else if (syncOutcome.eligible && !syncOutcome.windowInitialized) {
+				activationReason = "malformed-window-state";
 			} else {
 				const remoteResolution = await resolveCodexContextProvider(ctx, ctx.model, config.gatewayContextModels);
 				activationReason = remoteResolution.ok ? "codex-context-unavailable" : remoteResolution.reason;
@@ -1099,25 +1141,20 @@ export default function registerCompactionExtension(
 	pi.on("session_before_compact", (event, ctx) => handleSessionBeforeCompact(event, ctx, dependencies, remoteContextActive));
 	pi.on("session_compact", (event, _ctx) => contextWindows.recordCompaction(event.compactionEntry.details));
 	pi.on("session_shutdown", () => {
+		contextWindowReady = false;
 		contextWindows.reset();
 		tools.reset();
 	});
 	pi.on("model_select", async (event, ctx) => {
-		const active = await syncTools(ctx, event.model);
 		// Switching into a covered model mid-session must open the window
 		// lifecycle immediately: without an identity the request rewrite skips
 		// window metadata, the backend never ingests those turns, and the first
 		// new_context would trim pre-switch history that no history can recover.
-		// ensureInitialized is idempotent when a window already exists.
-		if (!active) return;
-		try {
-			contextWindows.ensureInitialized(pi, ctx, true);
-		} catch {
-			notifyRemoteContextFailure(ctx, "malformed-window-state");
-		}
+		// syncTools() activates and initializes the window when the model is covered.
+		await syncTools(ctx, event.model, { notifyWindowFailure: true });
 	});
 	pi.on("before_agent_start", async (_event, ctx) => {
-		await syncTools(ctx);
+		await syncTools(ctx, ctx.model, { notifyWindowFailure: true });
 	});
 	pi.on("before_provider_request", (event, ctx) => handleBeforeProviderRequest(event, ctx, dependencies.loadConfig, contextWindows, remoteContextActive));
 	pi.on("before_provider_headers", async (event, ctx) => {