pi-openai-toolkit 0.23.2 → 0.24.1

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

@@ -1,426 +0,0 @@
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import {
-	createAssistantMessageEventStream,
-	type AssistantMessage,
-	type AssistantMessageEvent,
-	type AssistantMessageEventStream,
-	type Context,
-	type ToolCall,
-} from "@earendil-works/pi-ai";
-import {
-	HISTORY_ACTIONS,
-	HISTORY_DESCRIPTION,
-	NOTES_ACTIONS,
-	NOTES_DESCRIPTION,
-} from "./tool-contract.ts";
-
-type JsonSchema = Record<string, unknown>;
-type ContextNamespace = "history" | "notes";
-
-const ACTIONS = {
-	history: new Set<string>(HISTORY_ACTIONS),
-	notes: new Set<string>(NOTES_ACTIONS),
-} satisfies Record<ContextNamespace, ReadonlySet<string>>;
-
-function nullable(type: string, description?: string): JsonSchema {
-	return {
-		...(description ? { description } : {}),
-		anyOf: [{ type }, { type: "null" }],
-	};
-}
-
-function nullableRole(): JsonSchema {
-	return {
-		anyOf: [
-			{
-				type: "string",
-				enum: ["user", "assistant", "tool", "system", "developer"],
-			},
-			{ type: "null" },
-		],
-	};
-}
-
-function string(description?: string, encrypted = false): JsonSchema {
-	return {
-		type: "string",
-		...(description ? { description } : {}),
-		...(encrypted ? { encrypted: true } : {}),
-	};
-}
-
-function integer(minimum?: number): JsonSchema {
-	return {
-		type: "integer",
-		...(minimum === undefined ? {} : { minimum }),
-	};
-}
-
-function object(
-	properties: Record<string, JsonSchema>,
-	required?: string[],
-) {
-	return {
-		type: "object",
-		properties,
-		...(required ? { required } : {}),
-		additionalProperties: false,
-	};
-}
-
-function operation(
-	name: string,
-	description: string,
-	parameters: ReturnType<typeof object>,
-) {
-	return { type: "function", name, description, strict: false, parameters };
-}
-
-function historyNamespace(encrypted: boolean) {
-	return {
-		type: "namespace",
-		name: "history",
-		description: HISTORY_DESCRIPTION,
-		tools: [
-			operation(
-				"list_windows",
-				"List context windows",
-				object({
-					agent_name: nullable("string"),
-					limit: integer(1),
-					recent_first: { type: "boolean" },
-				}),
-			),
-			operation(
-				"list_items",
-				"List history items",
-				object({
-					agent_name: nullable("string"),
-					limit: integer(1),
-					max_chars_per_item: integer(1),
-					recent_first: { type: "boolean" },
-					role: nullableRole(),
-					tool_name: nullable("string"),
-					tool_namespace: nullable("string"),
-					window_id: nullable("string"),
-				}),
-			),
-			operation(
-				"read_item",
-				"Read history item range",
-				object(
-					{
-						agent_name: nullable("string"),
-						item_id: {
-							type: "string",
-							description: "Suffix from the item's [id: …] marker.",
-						},
-						limit_chars: integer(1),
-						offset_chars: integer(0),
-						window_id: { type: "string" },
-					},
-					["item_id", "window_id"],
-				),
-			),
-			operation(
-				"search_contents",
-				"Search history",
-				object(
-					{
-						agent_name: nullable("string"),
-						limit: integer(1),
-						query: string("Case-sensitive", encrypted),
-						recent_first: { type: "boolean" },
-						role: nullableRole(),
-						tool_name: nullable("string"),
-						tool_namespace: nullable("string"),
-						window_id: nullable("string"),
-					},
-					["query"],
-				),
-			),
-		],
-	};
-}
-
-function notesNamespace(encrypted: boolean) {
-	return {
-		type: "namespace",
-		name: "notes",
-		description: NOTES_DESCRIPTION,
-		tools: [
-			operation(
-				"list_files_by_prefix",
-				"List note files",
-				object({
-					file_order: {
-						type: "string",
-						enum: ["ascending", "descending"],
-					},
-					file_order_by: {
-						type: "string",
-						enum: ["name", "created_at", "updated_at"],
-					},
-					max_results: integer(1),
-					prefix: nullable("string"),
-				}),
-			),
-			operation(
-				"read_file",
-				"Read note file; line bounds inclusive, 1-based, negative from end",
-				object(
-					{
-						path: { type: "string" },
-						start_line: nullable("integer"),
-						stop_line: nullable("integer"),
-					},
-					["path"],
-				),
-			),
-			operation(
-				"search_contents",
-				"Search note lines by literal substring",
-				object(
-					{
-						max_files: integer(1),
-						max_matches_per_file: integer(1),
-						path_prefix: nullable("string"),
-						query: string("Case-sensitive", encrypted),
-						recent_file_first: { type: "boolean" },
-					},
-					["query"],
-				),
-			),
-			operation(
-				"append_to_file",
-				"Append text exactly",
-				object(
-					{
-						path: { type: "string" },
-						text: string(undefined, encrypted),
-					},
-					["text", "path"],
-				),
-			),
-			operation(
-				"write_file",
-				"Create or replace a note file",
-				object(
-					{
-						path: { type: "string" },
-						text: string(undefined, encrypted),
-					},
-					["text", "path"],
-				),
-			),
-		],
-	};
-}
-
-function contextNamespace(
-	name: ContextNamespace,
-	encrypted: boolean,
-): Record<string, unknown> {
-	const namespace = name === "history"
-		? historyNamespace(encrypted)
-		: notesNamespace(encrypted);
-	// Codex validates reserved schemas against its serialized contract: open
-	// objects, with numeric bounds omitted by its JsonSchema serializer.
-	if (!encrypted) return namespace;
-	return {
-		...namespace,
-		tools: namespace.tools.map((tool) => {
-			const { additionalProperties: _additionalProperties, ...parameters } = tool.parameters;
-			for (const property of Object.values(parameters.properties)) {
-				delete property["minimum"];
-			}
-			return { ...tool, parameters };
-		}),
-	};
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
-function namespaceName(value: unknown): ContextNamespace | undefined {
-	if (!isRecord(value)) return undefined;
-	const name = value["name"];
-	return (name === "history" || name === "notes") &&
-		(value["type"] === "function" || value["type"] === "namespace")
-		? name
-		: undefined;
-}
-
-function rewriteTools(
-	tools: readonly unknown[],
-	encrypted: boolean,
-): { tools: unknown[]; changed: boolean } {
-	let changed = false;
-	const rewritten = tools.map((tool) => {
-		const name = namespaceName(tool);
-		if (!name) return tool;
-		changed = true;
-		return contextNamespace(name, encrypted);
-	});
-	return { tools: rewritten, changed };
-}
-
-export function rewriteContextNamespaceTools(
-	payload: unknown,
-	options: { encrypted?: boolean } = {},
-): unknown {
-	if (!isRecord(payload)) return payload;
-	const encrypted = options.encrypted === true;
-	let changed = false;
-	let tools = payload["tools"];
-	if (Array.isArray(tools)) {
-		const result = rewriteTools(tools, encrypted);
-		tools = result.tools;
-		changed ||= result.changed;
-	}
-	let input = payload["input"];
-	if (Array.isArray(input)) {
-		input = input.map((item) => {
-			if (!isRecord(item) || !Array.isArray(item["tools"])) return item;
-			const result = rewriteTools(item["tools"], encrypted);
-			if (!result.changed) return item;
-			changed = true;
-			return { ...item, tools: result.tools };
-		});
-	}
-	return changed ? { ...payload, tools, input } : payload;
-}
-
-export function rewriteContextNamespaceCalls(payload: unknown): unknown {
-	if (!isRecord(payload) || !Array.isArray(payload.input)) return payload;
-	let changed = false;
-	const input = payload.input.map((item) => {
-		if (!isRecord(item) || item.type !== "function_call") return item;
-		if ((item.namespace !== "history" && item.namespace !== "notes") || item.name !== item.namespace) return item;
-		if (typeof item.arguments !== "string") return item;
-		let arguments_: unknown;
-		try {
-			arguments_ = JSON.parse(item.arguments) as unknown;
-		} catch {
-			return item;
-		}
-		if (!isRecord(arguments_) || typeof arguments_.action !== "string" || !ACTIONS[item.namespace].has(arguments_.action)) return item;
-		const { action: _action, ...rest } = arguments_;
-		changed = true;
-		return { ...item, name: arguments_.action, arguments: JSON.stringify(rest) };
-	});
-	return changed ? { ...payload, input } : payload;
-}
-
-export function hasContextNamespaceRouters(
-	context: Pick<Context, "tools">,
-): boolean {
-	const names = new Set(context.tools?.map((tool) => tool.name));
-	return names.has("history") && names.has("notes");
-}
-
-function routedAction(call: ToolCall): string | undefined {
-	if (call.namespace !== "history" && call.namespace !== "notes")
-		return undefined;
-	return ACTIONS[call.namespace].has(call.name) ? call.name : undefined;
-}
-
-function routeContextNamespaceToolCall(call: ToolCall): ToolCall {
-	const action = routedAction(call);
-	if (!action || !call.namespace) return call;
-	return {
-		...call,
-		name: call.namespace,
-		arguments: { action, ...call.arguments },
-	};
-}
-
-export function unrouteContextNamespaceToolCall(call: ToolCall): ToolCall {
-	if (
-		(call.namespace !== "history" && call.namespace !== "notes") ||
-		call.name !== call.namespace
-	)
-		return call;
-	const action = call.arguments["action"];
-	if (typeof action !== "string" || !ACTIONS[call.namespace].has(action))
-		return call;
-	const args = { ...call.arguments };
-	delete args["action"];
-	return { ...call, name: action, arguments: args };
-}
-
-function routeMessage(message: AssistantMessage): AssistantMessage {
-	return {
-		...message,
-		content: message.content.map((block) =>
-			block.type === "toolCall"
-				? routeContextNamespaceToolCall(block)
-				: block,
-		),
-	};
-}
-
-/**
- * Pi's native provider parser preserves Responses namespace calls, but the
- * agent loop resolves tools by ToolCall.name. Route the parsed assistant
- * message at the public message_end boundary before tool execution begins.
- */
-export function routeContextNamespaceToolMessage(message: AgentMessage): AgentMessage {
-	if (message.role !== "assistant") return message;
-	let changed = false;
-	const content = message.content.map((block) => {
-		if (block.type !== "toolCall") return block;
-		const routed = routeContextNamespaceToolCall(block);
-		changed ||= routed !== block;
-		return routed;
-	});
-	return changed ? { ...message, content } : message;
-}
-
-function routeEvent(event: AssistantMessageEvent): AssistantMessageEvent {
-	if (event.type === "done")
-		return { ...event, message: routeMessage(event.message) };
-	if (event.type === "error")
-		return { ...event, error: routeMessage(event.error) };
-	const partial = routeMessage(event.partial);
-	return event.type === "toolcall_end"
-		? {
-				...event,
-				toolCall: routeContextNamespaceToolCall(event.toolCall),
-				partial,
-			}
-		: { ...event, partial };
-}
-
-export function routeContextNamespaceToolStream(
-	source: AssistantMessageEventStream,
-): AssistantMessageEventStream {
-	const output = createAssistantMessageEventStream();
-	void (async () => {
-		let latest: AssistantMessage | undefined;
-		try {
-			for await (const event of source) {
-				const routed = routeEvent(event);
-				latest = routed.type === "done"
-					? routed.message
-					: routed.type === "error"
-						? routed.error
-						: routed.partial;
-				output.push(routed);
-				if (routed.type === "done") output.end(routed.message);
-				if (routed.type === "error") output.end(routed.error);
-			}
-		} catch (error) {
-			if (!latest) throw error;
-			const failed: AssistantMessage = {
-				...latest,
-				stopReason: "error",
-				errorMessage: error instanceof Error ? error.message : String(error),
-			};
-			output.push({ type: "error", reason: "error", error: failed });
-			output.end(failed);
-		}
-	})();
-	return output;
-}

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;
-	});
-}