pi-openai-toolkit 0.23.1 → 0.24.0

package/src/context-management/responses-tools.ts

@@ -1,238 +0,0 @@
-/**
- * Convert Pi tool declarations into Responses-API wire tools.
- *
- * Pi 1.3 exports `convertResponsesTools` only from
- * `@earendil-works/pi-ai/api/openai-responses-shared`, but Pi's extension module
- * aliases map a fixed allowlist of specifiers and do not include that subpath.
- * Importing it from an extension therefore fails at load time with
- * "Cannot find module", which silently disables every hook the extension owns.
- *
- * This module reproduces that conversion without the subpath import. The strict
- * JSON-schema rewrite is a faithful port of Pi's `makeStrictJsonSchema`: it must
- * stay byte-identical, because a compaction request has to declare the same tool
- * schema as the live request it continues.
- */
-import type { Tool } from "@earendil-works/pi-ai";
-
-export type ResponsesWireTool =
-	| { type: "function"; name: string; description: string; parameters: unknown; strict?: boolean | null }
-	| { type: "custom"; name: string; description: string; format: { type: string; syntax: string; definition: string } };
-
-export type ConvertResponsesToolsOptions = {
-	/** Value applied when a tool does not opt in explicitly. `null` means no default. */
-	strict?: boolean | null;
-	supportsStrictMode?: boolean;
-	supportsOpenAIGrammarTools?: boolean;
-};
-
-type JsonSchema = Record<string, unknown>;
-
-type ConstrainedSampling = {
-	type: "json_schema" | "grammar";
-	strict?: "require" | "prefer" | "ignore";
-	variants?: { openai_lark?: string; openai_regex?: string };
-};
-
-/** Keywords the strict subset cannot express. Kept in sync with Pi's implementation. */
-const UNSUPPORTED_STRICT_SCHEMA_KEYS = [
-	"$ref",
-	"$defs",
-	"definitions",
-	"allOf",
-	"oneOf",
-	"patternProperties",
-	"dependentSchemas",
-	"dependencies",
-	"unevaluatedProperties",
-	"propertyNames",
-	"contains",
-	"prefixItems",
-	"not",
-	"if",
-	"then",
-	"else",
-];
-
-class UnsupportedStrictJsonSchemaError extends Error {}
-
-function isJsonSchemaObject(value: unknown): value is JsonSchema {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isStructuredSchema(schema: unknown): boolean {
-	if (!isJsonSchemaObject(schema)) return false;
-	const types = typeof schema["type"] === "string"
-		? [schema["type"]]
-		: Array.isArray(schema["type"]) ? schema["type"] : [];
-	return types.includes("object")
-		|| types.includes("array")
-		|| schema["properties"] !== undefined
-		|| schema["items"] !== undefined;
-}
-
-function schemaAllowsNull(schema: unknown): boolean {
-	if (!isJsonSchemaObject(schema)) return false;
-	if (schema["type"] === "null" || (Array.isArray(schema["type"]) && schema["type"].includes("null"))) return true;
-	if (schema["const"] === null || (Array.isArray(schema["enum"]) && schema["enum"].includes(null))) return true;
-	return Array.isArray(schema["anyOf"]) && schema["anyOf"].some((variant) => schemaAllowsNull(variant));
-}
-
-function makeJsonSchemaNodeStrict(schema: unknown): void {	if (!isJsonSchemaObject(schema)) throw new UnsupportedStrictJsonSchemaError("boolean schemas are unsupported");
-	for (const key of UNSUPPORTED_STRICT_SCHEMA_KEYS) {
-		if (schema[key] !== undefined) throw new UnsupportedStrictJsonSchemaError(`${key} schemas are unsupported`);
-	}
-	if (schema["anyOf"] !== undefined) {
-		if (!Array.isArray(schema["anyOf"]) || schema["anyOf"].length === 0) {
-			throw new UnsupportedStrictJsonSchemaError("anyOf must contain at least one schema");
-		}
-		for (const variant of schema["anyOf"]) {
-			if (isStructuredSchema(variant)) throw new UnsupportedStrictJsonSchemaError("object and array unions are unsupported");
-			makeJsonSchemaNodeStrict(variant);
-		}
-	}
-	if (schema["items"] !== undefined) {
-		if (Array.isArray(schema["items"])) throw new UnsupportedStrictJsonSchemaError("tuple schemas are unsupported");
-		makeJsonSchemaNodeStrict(schema["items"]);
-	}
-	const isObjectSchema = schema["type"] === "object";
-	if (schema["properties"] !== undefined && !isObjectSchema) {
-		throw new UnsupportedStrictJsonSchemaError("properties require type object");
-	}
-	if (!isObjectSchema) return;
-	if (schema["additionalProperties"] !== undefined && schema["additionalProperties"] !== false) {
-		throw new UnsupportedStrictJsonSchemaError("schema-valued or true additionalProperties is unsupported");
-	}
-	if (schema["properties"] !== undefined && !isJsonSchemaObject(schema["properties"])) {
-		throw new UnsupportedStrictJsonSchemaError("object properties must be a schema map");
-	}
-	if (schema["required"] !== undefined
-		&& (!Array.isArray(schema["required"]) || schema["required"].some((key) => typeof key !== "string"))) {
-		throw new UnsupportedStrictJsonSchemaError("object required must be a string array");
-	}
-	const properties = isJsonSchemaObject(schema["properties"]) ? schema["properties"] : {};
-	const propertyNames = Object.keys(properties);
-	const required = new Set(Array.isArray(schema["required"]) ? schema["required"] as string[] : []);
-	if ([...required].some((key) => !propertyNames.includes(key))) {
-		throw new UnsupportedStrictJsonSchemaError("required contains an unknown property");
-	}
-	for (const [key, property] of Object.entries(properties)) {
-		makeJsonSchemaNodeStrict(property);
-		if (!required.has(key) && !schemaAllowsNull(property)) {
-			properties[key] = { anyOf: [property, { type: "null" }] };
-		}
-	}
-	schema["required"] = propertyNames;
-	schema["additionalProperties"] = false;
-}
-
-/** Convert a tool schema to the strict subset expected by provider constrained sampling. */
-function makeStrictJsonSchema(schema: unknown): unknown {
-	const cloned = structuredClone(schema);
-	if (!isJsonSchemaObject(cloned)) throw new UnsupportedStrictJsonSchemaError("root schema must have type object");
-	makeJsonSchemaNodeStrict(cloned);
-	if (cloned["type"] !== "object") throw new UnsupportedStrictJsonSchemaError("root schema must have type object");
-	return cloned;
-}
-
-function constrainedSamplingOf(tool: Tool): ConstrainedSampling | undefined {	const value = (tool as { constrainedSampling?: unknown }).constrainedSampling;
-	if (!value || typeof value !== "object") return undefined;
-	const type = (value as { type?: unknown }).type;
-	if (type !== "json_schema" && type !== "grammar") return undefined;
-	return value as ConstrainedSampling;
-}
-
-/** Only `openai_lark` / `openai_regex` variants can be expressed on the Responses wire. */
-function grammarOf(tool: Tool): { syntax: string; definition: string } | undefined {
-	const sampling = constrainedSamplingOf(tool);
-	if (sampling?.type !== "grammar") return undefined;
-	const lark = sampling.variants?.openai_lark;
-	const regex = sampling.variants?.openai_regex;
-	const hasLark = typeof lark === "string" && lark.trim().length > 0;
-	const hasRegex = typeof regex === "string" && regex.trim().length > 0;
-	if (!hasLark && !hasRegex) {
-		throw new Error(`Tool "${tool.name}" cannot use grammar constrained sampling: no supported grammar variant was provided.`);
-	}
-	return hasLark ? { syntax: "lark", definition: lark! } : { syntax: "regex", definition: regex! };
-}
-
-/** Whether the schema can be expressed in the strict subset at all. */
-function isStrictExpressible(parameters: unknown): boolean {
-	try {
-		makeStrictJsonSchema(parameters);
-		return true;
-	} catch (error) {
-		if (error instanceof UnsupportedStrictJsonSchemaError) return false;
-		throw error;
-	}
-}
-
-/** The reason `makeStrictJsonSchema` refused, for fail-closed error text. */
-function strictUnsupportedReason(parameters: unknown): string {
-	try {
-		makeStrictJsonSchema(parameters);
-		return "the schema is unsupported";
-	} catch (error) {
-		return error instanceof Error ? error.message : String(error);
-	}
-}
-
-/**
- * Resolve the effective strict flag for one tool, mirroring Pi's
- * `resolveJsonSchemaStrictSampling` + `defaultStrict` composition.
- *
- * For any `json_schema` constrained sampling, Pi ignores the declared
- * `strict` mode when the schema is expressible: it simply returns `true`.
- * The mode only matters on the failure path, where `require` throws and
- * everything else falls back to the caller's default. Pi's `defaultStrict`
- * is `options.strict === undefined ? false : options.strict`, so an explicit
- * `null` is forwarded verbatim onto the wire.
- */
-function strictFor(tool: Tool, options: ConvertResponsesToolsOptions): boolean | null {
-	const supportsStrictMode = options.supportsStrictMode ?? true;
-	const sampling = constrainedSamplingOf(tool);
-	const fallback = options.strict === undefined ? false : options.strict;
-	if (sampling?.type !== "json_schema") return fallback;
-	if (supportsStrictMode) {
-		if (isStrictExpressible(tool.parameters)) return true;
-		if (sampling.strict === "require") {
-			throw new Error(`Tool "${tool.name}" requires JSON-schema constrained sampling, but ${strictUnsupportedReason(tool.parameters)}.`);
-		}
-		return fallback;
-	}
-	if (sampling.strict === "require") {
-		throw new Error(`Tool "${tool.name}" requires JSON-schema constrained sampling, but strict tools are unsupported.`);
-	}
-	return fallback;
-}
-
-/** Mirror Pi's wire shape so compaction requests match ordinary Responses requests. */
-export function convertResponsesTools(
-	tools: readonly Tool[],
-	options: ConvertResponsesToolsOptions = {},
-): ResponsesWireTool[] {
-	const supportsStrictMode = options.supportsStrictMode ?? true;
-	const supportsOpenAIGrammarTools = options.supportsOpenAIGrammarTools ?? false;
-	return tools.map((tool) => {
-		if (supportsOpenAIGrammarTools) {
-			const grammar = grammarOf(tool);
-			if (grammar) {
-				return {
-					type: "custom" as const,
-					name: tool.name,
-					description: tool.description,
-					format: { type: "grammar", ...grammar },
-				};
-			}
-		}
-		const strict = strictFor(tool, options);
-		const wire: ResponsesWireTool = {
-			type: "function",
-			name: tool.name,
-			description: tool.description,
-			parameters: strict === true ? makeStrictJsonSchema(tool.parameters) : tool.parameters,
-		};
-		// Pi writes `strict` whenever the transport supports it, including `false` and `null`.
-		if (supportsStrictMode) wire.strict = strict;
-		return wire;
-	});
-}

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

@@ -1,62 +0,0 @@
-export const HISTORY_ACTIONS = [
-	"list_windows",
-	"list_items",
-	"read_item",
-	"search_contents",
-] as const;
-
-export const NOTES_ACTIONS = [
-	"list_files_by_prefix",
-	"read_file",
-	"search_contents",
-	"append_to_file",
-	"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.";
-
-export const NOTES_DESCRIPTION =
-	"Cross-window checkpoints on virtual paths. Relative uses current agent; cross-agent uses <agent>/notes[/path].";

package/src/context-management/tools.ts

@@ -1,371 +0,0 @@
-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 { ContextWindowIdentity, 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 interface ContextRolloverHandoff {
-	prepare(ctx: ExtensionContext): { triggerTurn: false; beforeSchedule: (identity: ContextWindowIdentity) => void } | undefined;
-}
-
-export function createContextManagementTools(
-	pi: ExtensionAPI,
-	manager: CodexContextWindowManager,
-	isActive: ContextActivity,
-	getGatewayModels: () => readonly string[] = () => [],
-	handoff?: ContextRolloverHandoff,
-): 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,
-		exposure: "direct",
-		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 scheduling = handoff?.prepare(ctx);
-			const started = await manager.startNewWindow(pi, ctx, {
-				triggerTurn: true,
-				signal,
-				trimPreviousWindow: true,
-				gatewayModels,
-				...scheduling,
-			});
-			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 },
-				...(started && scheduling ? { terminate: true } : {}),
-			};
-		},
-	};
-	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,
-		exposure: "direct",
-		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,
-		exposure: "direct",
-		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,
-		exposure: "direct",
-		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" | "excluded" | "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;
-		let published = 0;
-		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;
-			}
-			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";
-	}
-
-	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[],
-	handoff?: ContextRolloverHandoff,
-): ContextManagementToolController {
-	const controller = new ContextManagementToolController(pi);
-	controller.register(createContextManagementTools(pi, manager, isActive, getGatewayModels, handoff));
-	return controller;
-}
-
-export const _contextToolsTest = {
-	EMPTY_PARAMETERS,
-	NEW_CONTEXT_PARAMETERS,
-	HISTORY_PARAMETERS,
-	NOTES_PARAMETERS,
-	HISTORY_ACTION_FIELDS,
-	NOTES_ACTION_FIELDS,
-};