pi-openai-toolkit 0.23.2 → 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/scoped-compaction.ts

@@ -1,89 +0,0 @@
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import {
-	estimateTokens,
-	findCutPoint,
-	type FileOperations,
-	type SessionBeforeCompactEvent,
-	type SessionEntry,
-} from "@earendil-works/pi-coding-agent";
-import { isRecord } from "./types";
-import type { RemoteWindowCompactionInput } from "./window-manager";
-
-function addFileOperation(name: string, args: unknown, files: FileOperations): void {
-	if (!isRecord(args) || typeof args.path !== "string") return;
-	if (name === "read") files.read.add(args.path);
-	else if (name === "write") files.written.add(args.path);
-	else if (name === "edit") files.edited.add(args.path);
-}
-
-/** Only canonical, current-window operations may contribute summary file metadata. */
-function collectFileOperations(messages: readonly AgentMessage[], scope: RemoteWindowCompactionInput): FileOperations {
-	const files: FileOperations = { read: new Set(), written: new Set(), edited: new Set() };
-	const previous = scope.owningCompaction;
-	if (previous && isRecord(previous.details)) {
-		for (const path of Array.isArray(previous.details.readFiles) ? previous.details.readFiles : []) {
-			if (typeof path === "string") files.read.add(path);
-		}
-		for (const path of Array.isArray(previous.details.modifiedFiles) ? previous.details.modifiedFiles : []) {
-			if (typeof path === "string") files.edited.add(path);
-		}
-	}
-	for (const message of messages) {
-		if (message.role === "assistant") {
-			for (const block of message.content) if (block.type === "toolCall") addFileOperation(block.name, block.arguments, files);
-		} else if (message.role === "toolResult") {
-			for (const call of message.nestedCalls?.calls ?? []) addFileOperation(call.name, call.arguments, files);
-		}
-	}
-	return files;
-}
-
-/**
- * Adapt canonical contributions to the public cut-point primitive. These are
- * detached in-memory views with REAL source IDs, never entries to persist.
- * Omitted entries contribute nothing; edited messages replace their raw values.
- */
-export function prepareScopedNativeCompaction(
-	event: SessionBeforeCompactEvent,
-	scope: RemoteWindowCompactionInput,
-): SessionBeforeCompactEvent {
-	const entries: SessionEntry[] = [];
-	for (const projected of scope.entries) {
-		if (projected.sourceEntry.type === "compaction") continue;
-		const messages = projected.messages.filter((message) => message.role !== "system");
-		if (!messages.length) continue;
-		// A single retained ID cannot safely identify a split within one source.
-		if (messages.length !== 1) throw new Error("compaction-source-projection-unavailable");
-		entries.push({ type: "message", id: projected.sourceEntry.id, parentId: projected.sourceEntry.parentId,
-			timestamp: projected.sourceEntry.timestamp, message: structuredClone(messages[0]!) });
-	}
-	if (!entries.length) throw new Error("unsafe-compaction-retained-start");
-	const settings = event.preparation.settings;
-	if (!settings || !Number.isFinite(settings.keepRecentTokens) || !Number.isFinite(settings.reserveTokens)) {
-		throw new Error("compaction-settings-unavailable");
-	}
-	const owner = scope.owningCompaction;
-	const ownerIndex = owner ? event.branchEntries.findIndex((entry) => entry.id === owner.id) : -1;
-	if (owner && ownerIndex < scope.windowBoundaryIndex) throw new Error("compaction-owner-mismatch");
-	const lowerIndex = Math.max(scope.windowBoundaryIndex, ownerIndex);
-	const minimumKeptIndex = entries.findIndex((entry) => event.branchEntries.findIndex((raw) => raw.id === entry.id) >= lowerIndex);
-	if (minimumKeptIndex < 0) throw new Error("compaction-current-window-too-small");
-	const cut = findCutPoint(entries, minimumKeptIndex, entries.length, settings.keepRecentTokens);
-	const kept = entries[cut.firstKeptEntryIndex];
-	if (kept?.type !== "message" || kept.message.role === "toolResult") throw new Error("unsafe-compaction-retained-start");
-	const firstKeptEntryId = kept.id;
-	if (!firstKeptEntryId) throw new Error("unsafe-compaction-retained-start");
-	const messages = (start: number, end: number) => entries.slice(start, end).flatMap((entry) => entry.type === "message" ? [entry.message] : []);
-	const messagesToSummarize = messages(0, cut.isSplitTurn ? cut.turnStartIndex : cut.firstKeptEntryIndex);
-	const turnPrefixMessages = cut.isSplitTurn ? messages(cut.turnStartIndex, cut.firstKeptEntryIndex) : [];
-	return {
-		...event,
-		preparation: {
-			firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn: cut.isSplitTurn,
-			tokensBefore: scope.messages.reduce((tokens, message) => tokens + estimateTokens(message), 0),
-			previousSummary: scope.owningCompaction?.summary,
-			fileOps: collectFileOperations([...messagesToSummarize, ...turnPrefixMessages], scope),
-			settings: { ...settings },
-		},
-	};
-}

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].";