@oai404iao/pi-codex-runtime 0.1.0-alpha.1

package/src/providers/responses/text-renderer.ts

@@ -0,0 +1,147 @@
+import { INTERNAL_CITATION_MARKER } from "./citations.js";
+import { isInsideMarkdownCode, markdownCodeRanges, trailingCitationFragmentStart, trailingIndexedSourceFragmentStart } from "./markdown.js";
+import type { CitationSource, MessagePartState, WebSearchCitationSource } from "./types.js";
+
+export function createResponseTextRenderer(
+	webSearchCitationSources: ReadonlyMap<string, WebSearchCitationSource>,
+	historicalCitationSources: ReadonlyArray<CitationSource>,
+) {
+
+
+	const annotationUrl = (annotation: unknown): string | undefined => {
+		const candidate = annotation && typeof annotation === "object" ? annotation as Record<string, unknown> : undefined;
+		return candidate?.type === "url_citation" && typeof candidate.url === "string" && candidate.url.trim() ? candidate.url.trim() : undefined;
+	};
+
+	const annotationTitle = (annotation: unknown): string | undefined => {
+		const candidate = annotation && typeof annotation === "object" ? annotation as Record<string, unknown> : undefined;
+		return typeof candidate?.title === "string" && candidate.title.trim() ? candidate.title.trim() : undefined;
+	};
+
+	const markdownLinkText = (value: string): string => value.replace(/\\/g, "\\\\").replace(/]/g, "\\]").replace(/\n+/g, " ");
+
+	const markdownLinkUrl = (value: string): string => value.replace(/[)\s]/g, (char) => encodeURIComponent(char));
+
+	const containsMarkdownLink = (value: string): boolean => /\[[^\]\n]+\]\([^) \n]+\)/.test(value);
+
+	const citationSourceLabel = (source: CitationSource): string => {
+		try {
+			const hostname = new URL(source.url).hostname.replace(/^www\./, "");
+			if (hostname) return hostname;
+		} catch {
+			// Fall back to the result title or URL.
+		}
+		return source.title ?? source.url;
+	};
+
+	const citationSourceMarkdown = (source: CitationSource): string =>
+		`[${markdownLinkText(citationSourceLabel(source))}](${markdownLinkUrl(source.url)})`;
+
+	const renderInternalCitationMarkers = (text: string): string => {
+		const initialCodeRanges = markdownCodeRanges(text);
+		const fragmentStart = trailingCitationFragmentStart(text, initialCodeRanges);
+		const visibleText = fragmentStart === undefined ? text : text.slice(0, fragmentStart);
+		const codeRanges = fragmentStart === undefined ? initialCodeRanges : markdownCodeRanges(visibleText);
+		const markerPattern = new RegExp(INTERNAL_CITATION_MARKER.source, "g");
+		let cursor = 0;
+		let rendered = "";
+		for (const match of visibleText.matchAll(markerPattern)) {
+			const start = match.index ?? 0;
+			if (isInsideMarkdownCode(start, codeRanges)) continue;
+			rendered += visibleText.slice(cursor, start);
+			const seenUrls = new Set<string>();
+			const links: string[] = [];
+			for (const rawRef of match[1]?.split("") ?? []) {
+				const source = webSearchCitationSources.get(rawRef.trim());
+				if (!source || seenUrls.has(source.url)) continue;
+				seenUrls.add(source.url);
+				links.push(citationSourceMarkdown(source));
+			}
+			rendered += links.length > 0 ? `(${links.join(", ")})` : "";
+			cursor = start + match[0].length;
+		}
+		if (cursor === 0) return visibleText;
+		return rendered + visibleText.slice(cursor);
+	};
+
+	const renderIndexedSourceMarkers = (text: string): string => {
+		const initialCodeRanges = markdownCodeRanges(text);
+		const fragmentStart = trailingIndexedSourceFragmentStart(text, initialCodeRanges);
+		const visibleText = fragmentStart === undefined ? text : text.slice(0, fragmentStart);
+		const codeRanges = fragmentStart === undefined ? initialCodeRanges : markdownCodeRanges(visibleText);
+		const markerPattern = /【(\d+)†source】/gi;
+		let cursor = 0;
+		let rendered = "";
+		for (const match of visibleText.matchAll(markerPattern)) {
+			const start = match.index ?? 0;
+			if (isInsideMarkdownCode(start, codeRanges)) continue;
+			rendered += visibleText.slice(cursor, start);
+			const followingText = visibleText.slice(start + match[0].length);
+			const alreadyLinked = /^\s*(?:\(\s*)?\[[^\]\n]+\]\(https?:\/\/[^)\s]+\)/.test(followingText);
+			const sourceIndex = Number.parseInt(match[1] ?? "", 10);
+			const source = Number.isInteger(sourceIndex) ? historicalCitationSources[sourceIndex] : undefined;
+			rendered += alreadyLinked || !source ? "" : `(${citationSourceMarkdown(source)})`;
+			cursor = start + match[0].length;
+		}
+		if (cursor === 0) return visibleText;
+		return rendered + visibleText.slice(cursor);
+	};
+
+	const sourceMarkdown = (annotations: unknown[], citedUrls: Set<string>): string => {
+		const seen = new Set<string>();
+		const links: string[] = [];
+		for (const annotation of annotations) {
+			const url = annotationUrl(annotation);
+			if (!url || citedUrls.has(url) || seen.has(url)) continue;
+			seen.add(url);
+			links.push(`[${markdownLinkText(annotationTitle(annotation) ?? url)}](${markdownLinkUrl(url)})`);
+		}
+		return links.length > 0 ? `\n\nSources: ${links.join(", ")}` : "";
+	};
+
+	const renderOutputTextPart = (part: MessagePartState): string => {
+		const annotations = part.annotations ?? [];
+		if (part.type !== "output_text" || annotations.length === 0) return part.text;
+		const spans = annotations
+			.map((annotation) => {
+				const candidate = annotation && typeof annotation === "object" ? annotation as Record<string, unknown> : undefined;
+				const url = annotationUrl(annotation);
+				const start = candidate?.start_index;
+				const end = candidate?.end_index;
+				return typeof start === "number" && typeof end === "number" && url && Number.isInteger(start) && Number.isInteger(end) && start >= 0 && end > start && end <= part.text.length
+					? { start, end, url }
+					: undefined;
+			})
+			.filter((span): span is { start: number; end: number; url: string } => !!span)
+			.sort((a, b) => a.start - b.start || a.end - b.end);
+		const citedUrls = new Set<string>();
+		let cursor = 0;
+		let rendered = "";
+		for (const span of spans) {
+			if (span.start < cursor) continue;
+			rendered += part.text.slice(cursor, span.start);
+			const label = part.text.slice(span.start, span.end);
+			rendered += containsMarkdownLink(label)
+				? label
+				: `[${markdownLinkText(label)}](${markdownLinkUrl(span.url)})`;
+			citedUrls.add(span.url);
+			cursor = span.end;
+		}
+		if (cursor === 0) return part.text + sourceMarkdown(annotations, citedUrls);
+		rendered += part.text.slice(cursor);
+		return rendered + sourceMarkdown(annotations, citedUrls);
+	};
+
+	const renderMessageText = (parts: Map<number, MessagePartState>, citations = false): string =>
+		Array.from(parts.entries())
+			.sort(([a], [b]) => a - b)
+			.map(([, part]) => {
+				const text = citations ? renderOutputTextPart(part) : part.text;
+				return part.type === "output_text"
+					? renderIndexedSourceMarkers(renderInternalCitationMarkers(text))
+					: text;
+			})
+			.join("");
+
+	return { renderMessageText };
+}

package/src/providers/responses/text.ts

@@ -0,0 +1,32 @@
+export function shortHash(str: string): string {
+	let h1 = 0xdeadbeef;
+	let h2 = 0x41c6ce57;
+	for (let i = 0; i < str.length; i++) {
+		const ch = str.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+	h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+	return (h2 >>> 0).toString(36) + (h1 >>> 0).toString(36);
+}
+
+export function parseStreamingJson(partialJson: string): Record<string, unknown> {
+	if (!partialJson || partialJson.trim() === "") return {};
+	try {
+		return JSON.parse(partialJson) as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+export function sanitizeSurrogates(text: string): string {
+	return text.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "");
+}
+
+export function localToolName(namespace: unknown, name: string): string {
+	if (typeof namespace !== "string" || namespace === "" || namespace === "functions") return name;
+	if (namespace === "web" && name === "run") return "web_search";
+	if (namespace === "image_gen" && name === "imagegen") return "image_generation";
+	return name;
+}

package/src/providers/responses/tool-identity.ts

@@ -0,0 +1,25 @@
+const TOOL_NAMESPACE_SIGNATURE_PREFIX = "pi:codex-tool-namespace:";
+
+export function encodeToolNamespaceSignature(namespace: unknown, name: string): string | undefined {
+	if (typeof namespace !== "string" || !namespace) return undefined;
+	return `${TOOL_NAMESPACE_SIGNATURE_PREFIX}${JSON.stringify({ namespace, name })}`;
+}
+
+export function wireToolIdentity(
+	name: string,
+	thoughtSignature: string | undefined,
+): { name: string; namespace?: string } {
+	if (!thoughtSignature?.startsWith(TOOL_NAMESPACE_SIGNATURE_PREFIX)) return { name };
+	try {
+		const value = JSON.parse(thoughtSignature.slice(TOOL_NAMESPACE_SIGNATURE_PREFIX.length)) as {
+			namespace?: unknown;
+			name?: unknown;
+		};
+		if (typeof value.namespace === "string" && value.namespace && typeof value.name === "string" && value.name) {
+			return { namespace: value.namespace, name: value.name };
+		}
+	} catch {
+		// Ignore malformed local metadata and replay the Pi-visible tool name.
+	}
+	return { name };
+}

package/src/providers/responses/tools.ts

@@ -0,0 +1,14 @@
+import { type Tool } from "@earendil-works/pi-ai";
+import { type Tool as OpenAITool } from "openai/resources/responses/responses.js";
+import { type ConvertResponsesToolsOptions } from "./types.js";
+
+export function convertResponsesTools(tools: Tool[], options?: ConvertResponsesToolsOptions): OpenAITool[] {
+	const strict = options?.strict === undefined ? false : options.strict;
+	return tools.map((tool) => ({
+		type: "function",
+		name: tool.name,
+		description: tool.description,
+		parameters: tool.parameters as unknown as Record<string, unknown>,
+		strict,
+	}));
+}

package/src/providers/responses/types.ts

@@ -0,0 +1,113 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { type Context, type Usage } from "@earendil-works/pi-ai";
+import { type ResponseCreateParamsStreaming } from "openai/resources/responses/responses.js";
+
+type MessageRole = Context["messages"][number]["role"];
+
+export type Message = Context["messages"][number];
+
+export interface ImageGenerationCallItem {
+	type: "image_generation_call";
+	id: string;
+	status: string;
+	result: string | null;
+	revised_prompt?: string;
+}
+
+export interface ImageGenerationCallBlock {
+	type: "image_generation_call";
+	item: ImageGenerationCallItem;
+}
+
+export interface ReplayableWebSearchCallItem {
+	type: "web_search_call";
+	id: string;
+	status: "completed";
+	action: Record<string, unknown>;
+	results?: Array<Record<string, unknown>>;
+}
+
+export interface CitationSource {
+	url: string;
+	title?: string;
+}
+
+export interface WebSearchCitationSource extends CitationSource {
+	refId: string;
+}
+
+export type ReplayableResponseMessageContent =
+	| { type: "output_text"; text: string; annotations: Array<Record<string, unknown>> }
+	| { type: "refusal"; refusal: string };
+
+export interface ReplayableResponseMessageItem {
+	type: "message";
+	id: string;
+	role: "assistant";
+	status: "completed";
+	content: ReplayableResponseMessageContent[];
+	phase?: TextSignaturePhase;
+}
+
+export type InternalAssistantContent = Extract<Message, { role: "assistant" }>["content"][number] | ImageGenerationCallBlock;
+
+export interface OpenAIResponsesStreamOptions {
+	serviceTier?: ResponseCreateParamsStreaming["service_tier"];
+	resolveServiceTier?: (
+		responseServiceTier: ResponseCreateParamsStreaming["service_tier"] | undefined,
+		requestServiceTier: ResponseCreateParamsStreaming["service_tier"] | undefined,
+	) => ResponseCreateParamsStreaming["service_tier"] | undefined;
+	applyServiceTierPricing?: (usage: Usage, serviceTier: ResponseCreateParamsStreaming["service_tier"] | undefined) => void;
+	webSearchCitationSources?: ReadonlyArray<WebSearchCitationSource>;
+	historicalCitationSources?: ReadonlyArray<CitationSource>;
+}
+
+export type TextSignaturePhase = "commentary" | "final_answer";
+
+export interface ConvertResponsesMessagesOptions {
+	includeSystemPrompt?: boolean;
+}
+
+export interface ConvertResponsesToolsOptions {
+	strict?: boolean | null;
+}
+
+export type ThinkingBlock = Extract<AssistantMessage["content"][number], { type: "thinking" }>;
+
+export type TextBlock = Extract<AssistantMessage["content"][number], { type: "text" }>;
+
+export type ToolCallBlock = Extract<AssistantMessage["content"][number], { type: "toolCall" }> & { partialJson?: string; partialInput?: string };
+
+export type ReasoningState = {
+	kind: "reasoning";
+	blockIndex: number;
+	block: ThinkingBlock;
+	summaryParts: Map<number, { text: string }>;
+};
+
+export type MessagePartState = { type: "output_text" | "refusal"; text: string; annotations?: unknown[] };
+
+export type MessageState = {
+	kind: "message";
+	blockIndex: number;
+	block: TextBlock;
+	parts: Map<number, MessagePartState>;
+};
+
+export type FunctionCallState = {
+	kind: "function_call";
+	blockIndex: number;
+	block: ToolCallBlock;
+};
+
+export type CustomToolCallState = {
+	kind: "custom_tool_call";
+	blockIndex: number;
+	block: ToolCallBlock;
+	itemId: string;
+	sourceItemId?: string;
+	callId: string;
+	input: string;
+};
+
+export type OutputState = ReasoningState | MessageState | FunctionCallState | CustomToolCallState;

package/src/providers/responses/usage.ts

@@ -0,0 +1,53 @@
+import { calculateCost, type Api, type AssistantMessage, type Model, type Usage } from "@earendil-works/pi-ai";
+import type { ResponseStreamEvent } from "openai/resources/responses/responses.js";
+import type { OpenAIResponsesStreamOptions } from "./types.js";
+
+export function finalizeResponseUsage(
+	response: Extract<ResponseStreamEvent, { type: "response.completed" }>["response"],
+	model: Model<Api>,
+	output: AssistantMessage,
+	options?: OpenAIResponsesStreamOptions,
+): void {
+	if (response?.usage) {
+		const cachedTokens = response.usage.input_tokens_details?.cached_tokens || 0;
+		const reasoningTokens = (response.usage as { output_tokens_details?: { reasoning_tokens?: number } }).output_tokens_details?.reasoning_tokens || 0;
+		output.usage = {
+			input: (response.usage.input_tokens || 0) - cachedTokens,
+			output: response.usage.output_tokens || 0,
+			cacheRead: cachedTokens,
+			cacheWrite: 0,
+			totalTokens: response.usage.total_tokens || 0,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		};
+		(output.usage as Usage & { reasoning?: number }).reasoning = reasoningTokens;
+	}
+	calculateCost(model, output.usage);
+	if (options?.applyServiceTierPricing) {
+		const serviceTier = options.resolveServiceTier
+			? options.resolveServiceTier(response?.service_tier, options.serviceTier)
+			: (response?.service_tier ?? options.serviceTier);
+		options.applyServiceTierPricing(output.usage, serviceTier);
+	}
+	output.stopReason = mapStopReason(response?.status);
+	if (output.content.some((block) => block.type === "toolCall") && output.stopReason === "stop") {
+		output.stopReason = "toolUse";
+	}
+}
+
+function mapStopReason(status: string | undefined): AssistantMessage["stopReason"] {
+	if (!status) return "stop";
+	switch (status) {
+		case "completed":
+			return "stop";
+		case "incomplete":
+			return "length";
+		case "failed":
+		case "cancelled":
+			return "error";
+		case "in_progress":
+		case "queued":
+			return "stop";
+		default:
+			throw new Error(`Unhandled stop reason: ${status}`);
+	}
+}

package/src/reserved-tools/image-generation.ts

@@ -0,0 +1,53 @@
+/*
+ * SPDX-FileCopyrightText: 2025 OpenAI
+ * SPDX-FileCopyrightText: 2026 oai404iao
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Modified TypeScript compatibility serialization derived from the namespace
+ * tool construction in OpenAI Codex at revision
+ * eb9dceba1a2e658142a456c5898836774835616b.
+ *
+ * This preserves the reviewed `web.run` and `image_gen.imagegen` declaration
+ * shapes for this package's internal Responses Lite compatibility path. It is
+ * not an OpenAI-supported public API contract. Immutable upstream blob IDs,
+ * source hashes, and local compatibility fingerprints are recorded in
+ * provenance/openai-codex-eb9dceba-reserved-tools.json.
+ *
+ * See THIRD_PARTY_NOTICES.md and LICENSES/Apache-2.0.txt.
+ */
+
+import type { CodexReservedNamespaceTool } from "./types.js";
+
+export const IMAGE_GENERATION_NAMESPACE: CodexReservedNamespaceTool = {
+		type: "namespace",
+		name: "image_gen",
+		description: "Tools in the image_gen namespace.",
+		tools: [
+			{
+				type: "function",
+				name: "imagegen",
+				description: "The `image_gen.imagegen` tool enables image generation from descriptions and editing of existing images based on specific instructions. Use it when:\n\n- The user requests an image based on a scene description, such as a diagram, portrait, comic, meme, or any other visual.\n- The user wants to modify an attached or previously generated image with specific changes, including adding or removing elements, altering colors, improving quality/resolution, or transforming the style (e.g., cartoon, oil painting).\n\nGuidelines:\n- imagegen needs a few minutes to finish. In code-mode, use the first-line @exec directive to give the initial call 120 seconds and the same yield for any waits that follow. Once it finishes, return the image with generatedImage(result).\n- Omit both `referenced_image_paths` and `num_last_images_to_include` when generating a brand new image.\n- For edits, use `referenced_image_paths` when every target image has a local file path.\n- If you have not seen a local image yet, use `view_image` to inspect it before editing.\n- Use `num_last_images_to_include` only when at least one target image has no local file path.\n- Set `num_last_images_to_include` to the smallest number of recent conversation images that includes every target image, up to 5.\n- Never provide both `referenced_image_paths` and `num_last_images_to_include`.\n- If neither mechanism can include every target image, ask the user to attach the missing images again.\n- Directly generate the image without reconfirmation or clarification unless required images must be attached again.\n- Always use this tool for image editing unless the user explicitly requests otherwise. Do not use the `python` tool for image editing unless specifically instructed.\n",
+				strict: false,
+				parameters: {
+					type: "object",
+					properties: {
+						num_last_images_to_include: {
+							type: ["integer", "null"],
+						},
+						prompt: {
+							type: "string",
+						},
+						referenced_image_paths: {
+							type: ["array", "null"],
+							items: {
+								type: "string",
+								description: "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
+							},
+						},
+					},
+					required: ["prompt"],
+					additionalProperties: false,
+				},
+			},
+		],
+	};

package/src/reserved-tools/types.ts

@@ -0,0 +1,32 @@
+/*
+ * SPDX-FileCopyrightText: 2025 OpenAI
+ * SPDX-FileCopyrightText: 2026 oai404iao
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Modified TypeScript compatibility serialization derived from the namespace
+ * tool construction in OpenAI Codex at revision
+ * eb9dceba1a2e658142a456c5898836774835616b.
+ *
+ * This preserves the reviewed `web.run` and `image_gen.imagegen` declaration
+ * shapes for this package's internal Responses Lite compatibility path. It is
+ * not an OpenAI-supported public API contract. Immutable upstream blob IDs,
+ * source hashes, and local compatibility fingerprints are recorded in
+ * provenance/openai-codex-eb9dceba-reserved-tools.json.
+ *
+ * See THIRD_PARTY_NOTICES.md and LICENSES/Apache-2.0.txt.
+ */
+
+export type CodexReservedToolName = "web_search" | "image_generation";
+
+export interface CodexReservedNamespaceTool {
+	type: "namespace";
+	name: "web" | "image_gen";
+	description: string;
+	tools: Array<{
+		type: "function";
+		name: "run" | "imagegen";
+		description: string;
+		strict: false;
+		parameters: Record<string, unknown>;
+	}>;
+}