pi-openai-toolkit 0.14.13 → 0.15.1

package/src/context-management/tools.ts

@@ -1,347 +1,353 @@
-import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { StringEnum, Type } from "@earendil-works/pi-ai";
-import { executeHistoryNotesTool, type CodexHistoryNotesDetails } from "./history-notes";
-import { type CodexContextWindowManager } from "./window-manager";
-import {
-	HISTORY_ACTION_FIELDS,
-	HISTORY_ENDPOINTS,
-	NOTES_ACTION_FIELDS,
-	NOTES_ENDPOINTS,
-} from "./history-notes";
-import type { HistoryAction, NotesAction } from "./types";
-
-const EMPTY_PARAMETERS = Type.Object({}, { additionalProperties: false });
-
-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[]];
-
-export const HISTORY_PARAMETERS = Type.Object({
-	action: StringEnum(HISTORY_ACTIONS),
-	agent_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-	item_id: Type.Optional(Type.String()),
-	limit: Type.Optional(Type.Integer({ minimum: 1 })),
-	limit_chars: Type.Optional(Type.Integer({ minimum: 1 })),
-	max_chars_per_item: Type.Optional(Type.Integer({ minimum: 1 })),
-	offset_chars: Type.Optional(Type.Integer({ minimum: 0 })),
-	query: Type.Optional(Type.String()),
-	recent_first: Type.Optional(Type.Boolean()),
-	role: Type.Optional(Type.Union([StringEnum(["user", "assistant", "tool", "system", "developer"] as const), Type.Null()])),
-	tool_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-	tool_namespace: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-	window_id: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-}, { additionalProperties: false });
-
-export const NOTES_PARAMETERS = Type.Object({
-	action: StringEnum(NOTES_ACTIONS),
-	file_order: Type.Optional(StringEnum(["ascending", "descending"] as const)),
-	file_order_by: Type.Optional(StringEnum(["name", "created_at", "updated_at"] as const)),
-	max_files: Type.Optional(Type.Integer({ minimum: 1 })),
-	max_matches_per_file: Type.Optional(Type.Integer({ minimum: 1 })),
-	max_results: Type.Optional(Type.Integer({ minimum: 1 })),
-	path: Type.Optional(Type.String()),
-	path_prefix: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-	prefix: Type.Optional(Type.Union([Type.String(), Type.Null()])),
-	query: Type.Optional(Type.String()),
-	recent_file_first: Type.Optional(Type.Boolean()),
-	start_line: Type.Optional(Type.Union([Type.Integer(), Type.Null()])),
-	stop_line: Type.Optional(Type.Union([Type.Integer(), Type.Null()])),
-	text: Type.Optional(Type.String()),
-}, { additionalProperties: false });
-
-export interface NewContextDetails { started: boolean; }
-
-export const NEW_CONTEXT_PARAMETERS = Type.Object({}, { additionalProperties: false });
-
-export const NEW_CONTEXT_CHECKPOINT_REQUIRED_MESSAGE =
-	"new_context refused: no persisted successful notes checkpoint in the current context window. "
-	+ "Write the active request, decisions, progress and next steps with notes append_to_file or write_file, "
-	+ "wait until that notes result is persisted, then retry new_context in a later tool turn. "
-	+ "Do not pass force arguments and do not repeat new_context while a rollover is already scheduled.";
-
-export const NEW_CONTEXT_COOLDOWN_MESSAGE =
-	"new_context refused: this window was entered by a context switch and has not run any substantive "
-	+ "tool yet. Read the checkpoint receipt with notes read_file, continue the active task with real "
-	+ "tools, and call new_context only once this window has produced tool activity.";
-export interface ContextRemainingDetails {
-	remainingTokens?: number;
-	windowId?: string;
-	contextWindow: number;
-}
-
-export type ContextManagementTools = {
-	newContext: ToolDefinition<typeof NEW_CONTEXT_PARAMETERS, NewContextDetails>;
-	getContextRemaining: ToolDefinition<typeof EMPTY_PARAMETERS, ContextRemainingDetails>;
-	history: ToolDefinition<typeof HISTORY_PARAMETERS, CodexHistoryNotesDetails>;
-	notes: ToolDefinition<typeof NOTES_PARAMETERS, CodexHistoryNotesDetails>;
-};
-
-export function createContextManagementTools(
-	pi: ExtensionAPI,
-	manager: CodexContextWindowManager,
-	isActive: (ctx: ExtensionContext) => Promise<boolean> | boolean,
-	getGatewayModels: () => readonly string[] = () => [],
-): ContextManagementTools {
-	const assertActive = async (ctx: ExtensionContext): Promise<void> => {
-		if (!(await isActive(ctx))) throw new Error("remote-context-inactive");
-	};
-	const newContext: ToolDefinition<typeof NEW_CONTEXT_PARAMETERS, NewContextDetails> = {
-		name: "new_context",
-		label: "new_context",
-		description: "Start a new remote Codex context window without generating a conversation summary. Requires a persisted successful notes checkpoint in the current window.",
-		parameters: NEW_CONTEXT_PARAMETERS,
-		promptSnippet: "Start a new remote Codex context window without summarizing history.",
-		promptGuidelines: [
-			"Before this new_context call, checkpoint active work in notes; only a persisted successful notes append/write in the current window unlocks this rollover, and no conversation summary carries over.",
-			"A successful new_context completes one context switch. In the next window, read the checkpoint receipt first when present, then resume the active user task; do not immediately create another checkpoint or call new_context as part of that handoff.",
-			"Wait for the notes tool result before calling new_context; an in-flight or failed write is not a checkpoint. If new_context reports that a rollover is already scheduled, do not call it again in the same window.",
-		],
-		executionMode: "sequential",
-		async execute(_id, _params, signal, _update, ctx) {
-			await assertActive(ctx);
-			manager.synchronize(ctx);
-			if (manager.hasPendingRollover(ctx)) {
-				return {
-					content: [{ type: "text", text: "A new context window is already scheduled." }],
-					details: { started: false },
-				};
-			}
-			if (!manager.canRolloverFromCurrentWindow(ctx)) {
-				return {
-					content: [{ type: "text", text: NEW_CONTEXT_COOLDOWN_MESSAGE }],
-					details: { started: false },
-				};
-			}
-			if (!manager.hasNotesCheckpointSinceBoundary(ctx)) {
-				throw new Error(NEW_CONTEXT_CHECKPOINT_REQUIRED_MESSAGE);
-			}
-			const started = await manager.startNewWindow(pi, ctx, {
-				triggerTurn: true,
-				signal,
-				trimPreviousWindow: true,
-			});
-			return {
-				content: [{
-					type: "text",
-					text: started
-						? "Context switch scheduled successfully. In the next context window, read the checkpoint receipt first when present, then resume the active user task; do not immediately create another checkpoint or call new_context."
-						: "A new context window is already scheduled.",
-				}],
-				details: { started },
-			};
-		},
-	};
-	const getContextRemaining: ToolDefinition<typeof EMPTY_PARAMETERS, ContextRemainingDetails> = {
-		name: "get_context_remaining",
-		label: "get_context_remaining",
-		description: "Get the remaining tokens in the current remote Codex context window.",
-		parameters: EMPTY_PARAMETERS,
-		async execute(_id, _params, _signal, _update, ctx) {
-			await assertActive(ctx);
-			const remaining = manager.remaining(ctx);
-			return {
-				content: [{ type: "text", text: remaining.remainingTokens === undefined ? "You have unknown tokens left in this context window." : `You have ${remaining.remainingTokens} tokens left in this context window.` }],
-				details: remaining,
-			};
-		},
-	};
-	const history: ToolDefinition<typeof HISTORY_PARAMETERS, CodexHistoryNotesDetails> = {
-		name: "history",
-		label: "history",
-		description: "Search or read prior remote Codex context-window history. Pass IDs unchanged.",
-		parameters: HISTORY_PARAMETERS,
-		promptSnippet: "Search or read prior remote Codex context-window history.",
-		promptGuidelines: [
-			"When the user asks about decisions, code, or details from earlier in the conversation that are no longer in the current context window, use history first instead of relying on fragments that survived compaction.",
-			"Use read_item with the exact item_id returned by list_items or search_contents; never rewrite, truncate, or guess IDs.",
-			"Before starting a new context window, use history to verify which earlier work the user still expects to be honored, then checkpoint anything not yet durable in notes.",
-			"Prefer search_contents over list_items when you only need a known fact; list_items is for getting an overview of what windows and items exist.",
-			"History is read-only; make no edits through it. Edits and durable checkpoints belong to notes.",
-		],
-		execute: async (_id, params, _signal, _update, ctx) => {
-			await assertActive(ctx);
-			return executeHistoryNotesTool("history", params.action, params as Record<string, unknown>, ctx, _signal, getGatewayModels());
-		},
-	};
-	const notes: ToolDefinition<typeof NOTES_PARAMETERS, CodexHistoryNotesDetails> = {
-		name: "notes",
-		label: "notes",
-		description: "Read and checkpoint remote Codex notes across context windows.",
-		parameters: NOTES_PARAMETERS,
-		promptSnippet: "Read and checkpoint remote Codex notes across context windows.",
-		promptGuidelines: [
-			"Before calling new_context, checkpoint the current turn's active work (unfinished tasks, decisions, open questions, references) into notes with append_to_file or write_file so it survives the window change; wait for that result to be persisted before calling new_context.",
-			"After a successful new_context handoff, read the checkpoint receipt first when present and resume the active user task; do not immediately create another checkpoint or call new_context unless a later rollover is actually needed.",
-			"When a large task spans multiple context windows, keep a running note per line of work and read it at the start of each new window; append new state instead of replacing it unless the note is stale.",
-			"Prefer read_file or search_contents for looking things up; reserve write_file for explicit rewrite/clear and append_to_file for incremental state.",
-			"Keep note text concise and self-contained: it may be read later without the rest of the conversation, so include identifiers and verbatim key decisions, not hearsay summaries.",
-			"Do not store live credentials, API keys, or full request bodies in notes; record the fact and where it lives instead.",
-		],
-		executionMode: "sequential",
-		execute: async (_id, params, _signal, _update, ctx) => {
-			await assertActive(ctx);
-			return executeHistoryNotesTool("notes", params.action, params as Record<string, unknown>, ctx, _signal, getGatewayModels());
-		},
-	};
-	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, {
-		description: string;
-		parameters: unknown;
-		promptGuidelines?: string[];
-	}>();
-	private registered = false;
-	private verifiedOnce = false;
-
-	constructor(private readonly pi: ExtensionAPI) {}
-
-	register(tools: ContextManagementTools): boolean {
-		const definitions = [tools.newContext, tools.getContextRemaining, tools.history, tools.notes];
-		const api = this.pi as ExtensionAPI & { registerTool?: (tool: unknown) => void };
-		if (typeof api.registerTool !== "function") return false;
-
-		// registerTool() is a registration method and is valid while Pi is loading
-		// the extension. Do not call action methods such as getAllTools() here;
-		// 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, {
-				description: definition.description,
-				parameters: definition.parameters,
-				promptGuidelines: definition.promptGuidelines,
-			});
-		}
-		// A successful call only proves the hand-off; it does not prove the runtime
-		// published the definitions. `checkRegistration()` reads that from Pi.
-		return 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?: () => PublishedTool[] };
-			if (typeof api.getAllTools !== "function") return "conflict";
-			available = api.getAllTools();
-		} catch {
-			// 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;
-		}
-		if (conflict) return "conflict";
-		if (missing) return "unverified";
-		this.verifiedOnce = true;
-		return "verified";
-	}
-
-	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 { synced: false, registrationState };
-		}
-		try {
-			const current = api.getActiveTools();
-			// Pi may activate a newly registered tool before the first sync. Once
-			// registration is verified, every registered name belongs to this
-			// controller: active models get all four, inactive models get none.
-			const next = active
-				? [...current, ...[...this.registeredNames].filter((name) => !current.includes(name))]
-				: current.filter((name) => !this.registeredNames.has(name));
-			if (next.length !== current.length) api.setActiveTools(next);
-			return { synced: true, registrationState };
-		} catch {
-			return { synced: false, registrationState };
-		}
-	}
-
-	reset(): void {
-		this.sync(false);
-	}
-	get isRegistered(): boolean { return this.checkRegistration() === "verified"; }
-	get registrationState(): ContextToolRegistrationState { return this.checkRegistration(); }
-}
-
-export function registerContextManagementTools(
-	pi: ExtensionAPI,
-	manager: CodexContextWindowManager,
-	isActive: (ctx: ExtensionContext) => Promise<boolean> | boolean,
-	getGatewayModels?: () => readonly string[],
-): ContextManagementToolController {
-	const controller = new ContextManagementToolController(pi);
-	controller.register(createContextManagementTools(pi, manager, isActive, getGatewayModels));
-	return controller;
-}
-
-export const _contextToolsTest = {
-	EMPTY_PARAMETERS,
-	NEW_CONTEXT_PARAMETERS,
-	HISTORY_PARAMETERS,
-	NOTES_PARAMETERS,
-	HISTORY_ACTION_FIELDS,
-	NOTES_ACTION_FIELDS,
-};
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { executeHistoryNotesTool, type CodexHistoryNotesDetails } from "./history-notes";
+import { type CodexContextWindowManager } from "./window-manager";
+import {
+	HISTORY_ACTION_FIELDS,
+	HISTORY_ENDPOINTS,
+	NOTES_ACTION_FIELDS,
+	NOTES_ENDPOINTS,
+} from "./history-notes";
+import type { HistoryAction, NotesAction } from "./types";
+
+const EMPTY_PARAMETERS = Type.Object({}, { additionalProperties: false });
+
+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[]];
+
+export const HISTORY_PARAMETERS = Type.Object({
+	action: StringEnum(HISTORY_ACTIONS),
+	agent_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+	item_id: Type.Optional(Type.String()),
+	limit: Type.Optional(Type.Integer({ minimum: 1 })),
+	limit_chars: Type.Optional(Type.Integer({ minimum: 1 })),
+	max_chars_per_item: Type.Optional(Type.Integer({ minimum: 1 })),
+	offset_chars: Type.Optional(Type.Integer({ minimum: 0 })),
+	query: Type.Optional(Type.String()),
+	recent_first: Type.Optional(Type.Boolean()),
+	role: Type.Optional(Type.Union([StringEnum(["user", "assistant", "tool", "system", "developer"] as const), Type.Null()])),
+	tool_name: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+	tool_namespace: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+	window_id: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+}, { additionalProperties: false });
+
+export const NOTES_PARAMETERS = Type.Object({
+	action: StringEnum(NOTES_ACTIONS),
+	file_order: Type.Optional(StringEnum(["ascending", "descending"] as const)),
+	file_order_by: Type.Optional(StringEnum(["name", "created_at", "updated_at"] as const)),
+	max_files: Type.Optional(Type.Integer({ minimum: 1 })),
+	max_matches_per_file: Type.Optional(Type.Integer({ minimum: 1 })),
+	max_results: Type.Optional(Type.Integer({ minimum: 1 })),
+	path: Type.Optional(Type.String()),
+	path_prefix: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+	prefix: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+	query: Type.Optional(Type.String()),
+	recent_file_first: Type.Optional(Type.Boolean()),
+	start_line: Type.Optional(Type.Union([Type.Integer(), Type.Null()])),
+	stop_line: Type.Optional(Type.Union([Type.Integer(), Type.Null()])),
+	text: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+
+export interface NewContextDetails { started: boolean; }
+
+export const NEW_CONTEXT_PARAMETERS = Type.Object({}, { additionalProperties: false });
+
+export const NEW_CONTEXT_CHECKPOINT_REQUIRED_MESSAGE =
+	"new_context refused: no persisted successful notes checkpoint in the current context window. "
+	+ "Write the active request, decisions, progress and next steps with notes append_to_file or write_file, "
+	+ "wait until that notes result is persisted, then retry new_context in a later tool turn. "
+	+ "Do not pass force arguments and do not repeat new_context while a rollover is already scheduled.";
+
+export const NEW_CONTEXT_COOLDOWN_MESSAGE =
+	"new_context refused: this window was entered by a context switch and has not run any substantive "
+	+ "tool yet. Read the checkpoint receipt with notes read_file, continue the active task with real "
+	+ "tools, and call new_context only once this window has produced tool activity.";
+export interface ContextRemainingDetails {
+	remainingTokens?: number;
+	windowId?: string;
+	contextWindow: number;
+}
+
+export type ContextManagementTools = {
+	newContext: ToolDefinition<typeof NEW_CONTEXT_PARAMETERS, NewContextDetails>;
+	getContextRemaining: ToolDefinition<typeof EMPTY_PARAMETERS, ContextRemainingDetails>;
+	history: ToolDefinition<typeof HISTORY_PARAMETERS, CodexHistoryNotesDetails>;
+	notes: ToolDefinition<typeof NOTES_PARAMETERS, CodexHistoryNotesDetails>;
+};
+
+export type ContextOperationPolicy = { active: boolean; gatewayModels: readonly string[] };
+type ContextActivity = (ctx: ExtensionContext) => Promise<boolean | ContextOperationPolicy> | boolean | ContextOperationPolicy;
+
+export function createContextManagementTools(
+	pi: ExtensionAPI,
+	manager: CodexContextWindowManager,
+	isActive: ContextActivity,
+	getGatewayModels: () => readonly string[] = () => [],
+): ContextManagementTools {
+	const assertActive = async (ctx: ExtensionContext): Promise<readonly string[]> => {
+		const policy = await isActive(ctx);
+		if (!(typeof policy === "boolean" ? policy : policy.active)) throw new Error("remote-context-inactive");
+		return typeof policy === "boolean" ? getGatewayModels() : policy.gatewayModels;
+	};
+	const newContext: ToolDefinition<typeof NEW_CONTEXT_PARAMETERS, NewContextDetails> = {
+		name: "new_context",
+		label: "new_context",
+		description: "Start a new remote Codex context window without generating a conversation summary. Requires a persisted successful notes checkpoint in the current window.",
+		parameters: NEW_CONTEXT_PARAMETERS,
+		promptSnippet: "Start a new remote Codex context window without summarizing history.",
+		promptGuidelines: [
+			"Before this new_context call, checkpoint active work in notes; only a persisted successful notes append/write in the current window unlocks this rollover, and no conversation summary carries over.",
+			"A successful new_context completes one context switch. In the next window, read the checkpoint receipt first when present, then resume the active user task; do not immediately create another checkpoint or call new_context as part of that handoff.",
+			"Wait for the notes tool result before calling new_context; an in-flight or failed write is not a checkpoint. If new_context reports that a rollover is already scheduled, do not call it again in the same window.",
+		],
+		executionMode: "sequential",
+		async execute(_id, _params, signal, _update, ctx) {
+			const gatewayModels = await assertActive(ctx);
+			manager.synchronize(ctx);
+			if (manager.hasPendingRollover(ctx)) {
+				return {
+					content: [{ type: "text", text: "A new context window is already scheduled." }],
+					details: { started: false },
+				};
+			}
+			if (!manager.canRolloverFromCurrentWindow(ctx)) {
+				return {
+					content: [{ type: "text", text: NEW_CONTEXT_COOLDOWN_MESSAGE }],
+					details: { started: false },
+				};
+			}
+			if (!manager.hasNotesCheckpointSinceBoundary(ctx)) {
+				throw new Error(NEW_CONTEXT_CHECKPOINT_REQUIRED_MESSAGE);
+			}
+			const started = await manager.startNewWindow(pi, ctx, {
+				triggerTurn: true,
+				signal,
+				trimPreviousWindow: true,
+				gatewayModels,
+			});
+			return {
+				content: [{
+					type: "text",
+					text: started
+						? "Context switch scheduled successfully. In the next context window, read the checkpoint receipt first when present, then resume the active user task; do not immediately create another checkpoint or call new_context."
+						: "A new context window is already scheduled.",
+				}],
+				details: { started },
+			};
+		},
+	};
+	const getContextRemaining: ToolDefinition<typeof EMPTY_PARAMETERS, ContextRemainingDetails> = {
+		name: "get_context_remaining",
+		label: "get_context_remaining",
+		description: "Get the remaining tokens in the current remote Codex context window.",
+		parameters: EMPTY_PARAMETERS,
+		async execute(_id, _params, _signal, _update, ctx) {
+			await assertActive(ctx);
+			const remaining = manager.remaining(ctx);
+			return {
+				content: [{ type: "text", text: remaining.remainingTokens === undefined ? "You have unknown tokens left in this context window." : `You have ${remaining.remainingTokens} tokens left in this context window.` }],
+				details: remaining,
+			};
+		},
+	};
+	const history: ToolDefinition<typeof HISTORY_PARAMETERS, CodexHistoryNotesDetails> = {
+		name: "history",
+		label: "history",
+		description: "Search or read prior remote Codex context-window history. Pass IDs unchanged.",
+		parameters: HISTORY_PARAMETERS,
+		promptSnippet: "Search or read prior remote Codex context-window history.",
+		promptGuidelines: [
+			"When the user asks about decisions, code, or details from earlier in the conversation that are no longer in the current context window, use history first instead of relying on fragments that survived compaction.",
+			"Use read_item with the exact item_id returned by list_items or search_contents; never rewrite, truncate, or guess IDs.",
+			"Before starting a new context window, use history to verify which earlier work the user still expects to be honored, then checkpoint anything not yet durable in notes.",
+			"Prefer search_contents over list_items when you only need a known fact; list_items is for getting an overview of what windows and items exist.",
+			"History is read-only; make no edits through it. Edits and durable checkpoints belong to notes.",
+		],
+		execute: async (_id, params, _signal, _update, ctx) => {
+			const gatewayModels = await assertActive(ctx);
+			return executeHistoryNotesTool("history", params.action, params as Record<string, unknown>, ctx, _signal, gatewayModels);
+		},
+	};
+	const notes: ToolDefinition<typeof NOTES_PARAMETERS, CodexHistoryNotesDetails> = {
+		name: "notes",
+		label: "notes",
+		description: "Read and checkpoint remote Codex notes across context windows.",
+		parameters: NOTES_PARAMETERS,
+		promptSnippet: "Read and checkpoint remote Codex notes across context windows.",
+		promptGuidelines: [
+			"Before calling new_context, checkpoint the current turn's active work (unfinished tasks, decisions, open questions, references) into notes with append_to_file or write_file so it survives the window change; wait for that result to be persisted before calling new_context.",
+			"After a successful new_context handoff, read the checkpoint receipt first when present and resume the active user task; do not immediately create another checkpoint or call new_context unless a later rollover is actually needed.",
+			"When a large task spans multiple context windows, keep a running note per line of work and read it at the start of each new window; append new state instead of replacing it unless the note is stale.",
+			"Prefer read_file or search_contents for looking things up; reserve write_file for explicit rewrite/clear and append_to_file for incremental state.",
+			"Keep note text concise and self-contained: it may be read later without the rest of the conversation, so include identifiers and verbatim key decisions, not hearsay summaries.",
+			"Do not store live credentials, API keys, or full request bodies in notes; record the fact and where it lives instead.",
+		],
+		executionMode: "sequential",
+		execute: async (_id, params, _signal, _update, ctx) => {
+			const gatewayModels = await assertActive(ctx);
+			return executeHistoryNotesTool("notes", params.action, params as Record<string, unknown>, ctx, _signal, gatewayModels);
+		},
+	};
+	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, {
+		description: string;
+		parameters: unknown;
+		promptGuidelines?: string[];
+	}>();
+	private registered = false;
+	private verifiedOnce = false;
+
+	constructor(private readonly pi: ExtensionAPI) {}
+
+	register(tools: ContextManagementTools): boolean {
+		const definitions = [tools.newContext, tools.getContextRemaining, tools.history, tools.notes];
+		const api = this.pi as ExtensionAPI & { registerTool?: (tool: unknown) => void };
+		if (typeof api.registerTool !== "function") return false;
+
+		// registerTool() is a registration method and is valid while Pi is loading
+		// the extension. Do not call action methods such as getAllTools() here;
+		// 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, {
+				description: definition.description,
+				parameters: definition.parameters,
+				promptGuidelines: definition.promptGuidelines,
+			});
+		}
+		// A successful call only proves the hand-off; it does not prove the runtime
+		// published the definitions. `checkRegistration()` reads that from Pi.
+		return 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?: () => PublishedTool[] };
+			if (typeof api.getAllTools !== "function") return "conflict";
+			available = api.getAllTools();
+		} catch {
+			// 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;
+		}
+		if (conflict) return "conflict";
+		if (missing) return "unverified";
+		this.verifiedOnce = true;
+		return "verified";
+	}
+
+	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 { synced: false, registrationState };
+		}
+		try {
+			const current = api.getActiveTools();
+			// Pi may activate a newly registered tool before the first sync. Once
+			// registration is verified, every registered name belongs to this
+			// controller: active models get all four, inactive models get none.
+			const next = active
+				? [...current, ...[...this.registeredNames].filter((name) => !current.includes(name))]
+				: current.filter((name) => !this.registeredNames.has(name));
+			if (next.length !== current.length) api.setActiveTools(next);
+			return { synced: true, registrationState };
+		} catch {
+			return { synced: false, registrationState };
+		}
+	}
+
+	reset(): void {
+		this.sync(false);
+	}
+	get isRegistered(): boolean { return this.checkRegistration() === "verified"; }
+	get registrationState(): ContextToolRegistrationState { return this.checkRegistration(); }
+}
+
+export function registerContextManagementTools(
+	pi: ExtensionAPI,
+	manager: CodexContextWindowManager,
+	isActive: ContextActivity,
+	getGatewayModels?: () => readonly string[],
+): ContextManagementToolController {
+	const controller = new ContextManagementToolController(pi);
+	controller.register(createContextManagementTools(pi, manager, isActive, getGatewayModels));
+	return controller;
+}
+
+export const _contextToolsTest = {
+	EMPTY_PARAMETERS,
+	NEW_CONTEXT_PARAMETERS,
+	HISTORY_PARAMETERS,
+	NOTES_PARAMETERS,
+	HISTORY_ACTION_FIELDS,
+	NOTES_ACTION_FIELDS,
+};