@raoxxxwq/pi-codebuddy-sdk 0.3.0

package/src/model-calibration.ts

@@ -0,0 +1,129 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+export interface CalibrationEnvironment {
+	internetEnvironment: string;
+	codebuddyConfigDir: string;
+	codebuddyExecutable: string;
+}
+
+export interface CapabilityMetric {
+	floor: number;
+	latest: number;
+	max: number;
+	observedAt: string;
+}
+
+export interface ModelCalibrationRecord {
+	modelId: string;
+	environment: CalibrationEnvironment;
+	capabilities: {
+		contextWindow?: CapabilityMetric;
+		maxTokens?: CapabilityMetric;
+	};
+}
+
+export interface CalibrationCache {
+	version: 1;
+	records: Record<string, ModelCalibrationRecord>;
+}
+
+const CALIBRATION_CACHE_VERSION = 1;
+export const DEFAULT_CALIBRATION_CACHE_PATH = join(homedir(), ".pi", "agent", "codebuddy-sdk-model-calibration.json");
+
+function normalizedValue(value: string | undefined | null): string {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : "default";
+}
+
+export function buildCalibrationEnvironment(codebuddyExecutable?: string): CalibrationEnvironment {
+	return {
+		internetEnvironment: normalizedValue(process.env.CODEBUDDY_INTERNET_ENVIRONMENT),
+		codebuddyConfigDir: normalizedValue(process.env.CODEBUDDY_CONFIG_DIR),
+		codebuddyExecutable: normalizedValue(codebuddyExecutable),
+	};
+}
+
+export function buildCalibrationKey(modelId: string, environment: CalibrationEnvironment): string {
+	return JSON.stringify({ modelId, ...environment });
+}
+
+export function loadCalibrationCache(path = DEFAULT_CALIBRATION_CACHE_PATH): CalibrationCache {
+	if (!existsSync(path)) return { version: CALIBRATION_CACHE_VERSION, records: {} };
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<CalibrationCache>;
+		if (parsed.version !== CALIBRATION_CACHE_VERSION || !parsed.records || typeof parsed.records !== "object") {
+			return { version: CALIBRATION_CACHE_VERSION, records: {} };
+		}
+		return { version: CALIBRATION_CACHE_VERSION, records: parsed.records };
+	} catch {
+		return { version: CALIBRATION_CACHE_VERSION, records: {} };
+	}
+}
+
+export function saveCalibrationCache(cache: CalibrationCache, path = DEFAULT_CALIBRATION_CACHE_PATH): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(cache, null, 2) + "\n");
+}
+
+export function getCalibrationRecord(
+	cache: CalibrationCache,
+	modelId: string,
+	environment: CalibrationEnvironment,
+): ModelCalibrationRecord | undefined {
+	return cache.records[buildCalibrationKey(modelId, environment)];
+}
+
+export function getContextWindowCalibration(
+	cache: CalibrationCache,
+	modelId: string,
+	environment: CalibrationEnvironment,
+): CapabilityMetric | undefined {
+	return getCalibrationRecord(cache, modelId, environment)?.capabilities.contextWindow;
+}
+
+export function applyContextWindowCalibrations<T extends { id: string; contextWindow: number }>(
+	models: T[],
+	cache: CalibrationCache,
+	environment: CalibrationEnvironment,
+): T[] {
+	return models.map((model) => {
+		const metric = getContextWindowCalibration(cache, model.id, environment);
+		if (!metric?.floor) return model;
+		return { ...model, contextWindow: metric.floor };
+	});
+}
+
+export function recordObservedContextWindow(
+	cache: CalibrationCache,
+	modelId: string,
+	environment: CalibrationEnvironment,
+	observed: number,
+): { changed: boolean; floorChanged: boolean; record: ModelCalibrationRecord } {
+	const key = buildCalibrationKey(modelId, environment);
+	const existing = cache.records[key];
+	const previous = existing?.capabilities.contextWindow;
+	const nextMetric: CapabilityMetric = {
+		floor: previous ? Math.min(previous.floor, observed) : observed,
+		latest: observed,
+		max: previous ? Math.max(previous.max, observed) : observed,
+		observedAt: new Date().toISOString(),
+	};
+	const nextRecord: ModelCalibrationRecord = {
+		modelId,
+		environment,
+		capabilities: {
+			...existing?.capabilities,
+			contextWindow: nextMetric,
+		},
+	};
+	cache.records[key] = nextRecord;
+	const changed =
+		!previous ||
+		previous.floor !== nextMetric.floor ||
+		previous.latest !== nextMetric.latest ||
+		previous.max !== nextMetric.max;
+	const floorChanged = !previous || previous.floor !== nextMetric.floor;
+	return { changed, floorChanged, record: nextRecord };
+}

package/src/models.ts

@@ -0,0 +1,79 @@
+// Dynamic model list from CodeBuddy SDK supportedModels().
+import type { ModelInfo } from "@tencent-ai/agent-sdk";
+
+export type PiModel = {
+	id: string;
+	name: string;
+	reasoning: boolean;
+	input: ("text" | "image")[];
+	contextWindow: number;
+	maxTokens: number;
+	thinkingLevelMap?: Record<string, string>;
+	cost: { input: number; output: number; cacheRead: number; cacheWrite: number };
+};
+
+const CONSERVATIVE_DEFAULT_CONTEXT = 65_536;
+const CONSERVATIVE_GEMINI_CONTEXT = 131_072;
+const DEFAULT_MAX_TOKENS = 8192;
+
+function detectThinking(id: string): boolean {
+	return /claude|gemini|gpt-5|hy3|deepseek|glm/i.test(id);
+}
+
+function detectImages(id: string): boolean {
+	return /claude|gemini|gpt/i.test(id);
+}
+
+export function conservativeContextWindow(id: string): number {
+	const lower = id.toLowerCase();
+	if (lower.includes("gemini")) return CONSERVATIVE_GEMINI_CONTEXT;
+	return CONSERVATIVE_DEFAULT_CONTEXT;
+}
+
+export function conservativeMaxTokens(id: string): number {
+	if (id.toLowerCase().includes("gpt")) return 16_384;
+	return DEFAULT_MAX_TOKENS;
+}
+
+export function rawModelsFromSdk(supported: Array<ModelInfo & { id?: string; name?: string }>): PiModel[] {
+	return supported
+		.map((m) => ({ id: m.id ?? m.value, name: m.name ?? m.displayName ?? m.id ?? m.value }))
+		.filter((m) => m.id)
+		.map((m) => ({
+			id: m.id!,
+			name: m.name || m.id!,
+			reasoning: detectThinking(m.id!),
+			input: detectImages(m.id!) ? ["text", "image"] as const : ["text"] as const,
+			contextWindow: conservativeContextWindow(m.id!),
+			maxTokens: conservativeMaxTokens(m.id!),
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		}));
+}
+
+export const FALLBACK_MODELS: PiModel[] = [
+	{
+		id: "hy3-preview-agent-ioa",
+		name: "Hunyuan 3 Preview",
+		reasoning: true,
+		input: ["text"],
+		contextWindow: conservativeContextWindow("hy3-preview-agent-ioa"),
+		maxTokens: DEFAULT_MAX_TOKENS,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	},
+];
+
+export function buildModels(models: PiModel[]): PiModel[] {
+	return models.map((m) => ({
+		...m,
+		cost: m.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	}));
+}
+
+export function codebuddyModelId(model: { id: string }): string {
+	return model.id;
+}
+
+export function resolveModel<T extends { id: string }>(models: T[], input: string): T | undefined {
+	const lower = input.toLowerCase();
+	return models.find((m) => m.id === lower || m.id.toLowerCase().includes(lower));
+}

package/src/query-state.ts

@@ -0,0 +1,80 @@
+// Query state: QueryContext class + context stack.
+//
+// All per-query and per-turn mutable state lives here. Reentrant queries
+// (subagents) push the parent context onto a stack and get a fresh instance.
+// Adding a new field = one property on the class.
+//
+// Extracted from index.ts so tests can import without activating the extension.
+
+import type { AssistantMessage, AssistantMessageEventStream, Model } from "@earendil-works/pi-ai";
+import type { McpResult } from "./extract-tool-results.js";
+
+export interface PendingToolCall {
+	toolName: string;
+	resolve: (result: McpResult) => void;
+}
+
+export class QueryContext {
+	// Query-scoped (fully isolated per query)
+	activeQuery: unknown | null = null;
+	currentPiStream: AssistantMessageEventStream | null = null;
+	latestCursor = 0;
+	pendingToolCalls = new Map<string, PendingToolCall>();
+	pendingResults = new Map<string, McpResult>();
+	turnToolCallIds: string[] = [];
+	nextHandlerIdx = 0;
+	deferredUserMessages: string[] = [];
+
+	// Per-turn (reset together)
+	turnOutput: AssistantMessage | null = null;
+	turnStarted = false;
+	turnSawStreamEvent = false;
+	turnSawToolCall = false;
+
+	get turnBlocks(): Array<any> {
+		if (!this.turnOutput) throw new Error("turnBlocks accessed before resetTurnState");
+		return this.turnOutput.content;
+	}
+
+	resetTurnState(model: Model<any>): void {
+		this.turnOutput = {
+			role: "assistant", content: [],
+			api: model.api, provider: model.provider, model: model.id,
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+			stopReason: "stop", timestamp: Date.now(),
+		};
+		this.turnStarted = false;
+		this.turnSawStreamEvent = false;
+		this.turnSawToolCall = false;
+		// turnToolCallIds and nextHandlerIdx are NOT reset — they persist across
+		// tool-result delivery callbacks within the same assistant message.
+	}
+}
+
+let _ctx = new QueryContext();
+const contextStack: QueryContext[] = [];
+
+export function ctx(): QueryContext { return _ctx; }
+
+export function stackDepth(): number { return contextStack.length; }
+
+export function pushContext(): void {
+	if (!_ctx.activeQuery) throw new Error("pushContext() called with no active query");
+	contextStack.push(_ctx);
+	_ctx = new QueryContext();
+}
+
+export function popContext(): void {
+	if (contextStack.length === 0) throw new Error("popContext() called with empty stack");
+	const parent = contextStack[contextStack.length - 1];
+	parent.deferredUserMessages.push(..._ctx.deferredUserMessages);
+	_ctx = contextStack.pop()!;
+}
+
+// Test-only: drop all state so test files can start from a clean module.
+// Not called from production.
+export function resetStack(): void {
+	_ctx = new QueryContext();
+	contextStack.length = 0;
+}

package/src/sdk-gate.ts

@@ -0,0 +1,17 @@
+// Serialize CodeBuddy SDK query() subprocesses — only one CLI at a time.
+
+let chain: Promise<void> = Promise.resolve();
+
+export function withSdkGate<T>(fn: () => Promise<T>): Promise<T> {
+	const run = chain.then(fn);
+	chain = run.then(() => undefined, () => undefined);
+	return run;
+}
+
+export async function drainQuery(q: AsyncIterable<unknown>): Promise<void> {
+	const timer = new Promise<void>((r) => setTimeout(r, 5000));
+	await Promise.race([
+		(async () => { for await (const _ of q) { /* drain */ } })(),
+		timer,
+	]);
+}

package/src/session-verify.ts

@@ -0,0 +1,38 @@
+// Pure session-file integrity check. Returns an array of warning strings;
+// callers decide how to surface them (debug log, piUI, diagDump, etc.).
+// Extracted from index.ts so tests can import without activating the extension.
+
+import { statSync, readFileSync } from "fs";
+
+export function verifyWrittenSession(jsonlPath: string, expectedSessionId: string, expectedRecordCount: number): string[] {
+	const warnings = [];
+	let st;
+	try {
+		st = statSync(jsonlPath);
+	} catch (e) {
+		warnings.push(`file missing after save — path=${jsonlPath} err=${e.message}`);
+		return warnings;
+	}
+	let content;
+	try {
+		content = readFileSync(jsonlPath, "utf8");
+	} catch (e) {
+		warnings.push(`file unreadable — path=${jsonlPath} size=${st.size} err=${e.message}`);
+		return warnings;
+	}
+	const lines = content.split("\n").filter((l) => l.trim().length > 0);
+	if (lines.length !== expectedRecordCount) {
+		warnings.push(`record count mismatch — expected=${expectedRecordCount} actual=${lines.length} path=${jsonlPath} bytes=${content.length}`);
+		return warnings;
+	}
+	try {
+		const firstRec = JSON.parse(lines[0]);
+		const lastRec = JSON.parse(lines[lines.length - 1]);
+		if (firstRec.sessionId !== expectedSessionId || lastRec.sessionId !== expectedSessionId) {
+			warnings.push(`sessionId drift — expected=${expectedSessionId} first=${firstRec.sessionId} last=${lastRec.sessionId}`);
+		}
+	} catch (e) {
+		warnings.push(`malformed JSONL — path=${jsonlPath} err=${e.message}`);
+	}
+	return warnings;
+}

package/src/skills.ts

@@ -0,0 +1,155 @@
+// Skills block extraction + MCP naming constants.
+// Extracted from index.ts so tests can import without activating the extension.
+
+import { extractAgentsAppend } from "./agents-md.js";
+
+export const MCP_SERVER_NAME = "custom_tools";
+export const MCP_TOOL_PREFIX = `mcp__${MCP_SERVER_NAME}__`;
+
+const SKILLS_START_MARKER = "The following skills provide specialized instructions for specific tasks.";
+const SKILLS_END_MARKER = "</available_skills>";
+const TOOL_GUIDANCE_MARKER = "CodeBuddy guidance:";
+const CORE_TOOL_ORDER = ["read", "edit", "write", "bash"] as const;
+
+const BUILTIN_TOOL_GUIDANCE: Record<string, string> = {
+	read: "Use this Pi tool to inspect file contents before answering file-specific questions or editing existing files. Prefer it over shelling out to cat/sed when reading files.",
+	write: "Use this Pi tool only when creating a new file or replacing a whole file is intended. Prefer edit for targeted changes to existing files.",
+	edit: "Use this Pi tool for targeted changes after reading the file. The oldText/old_string value must exactly match existing content; use the Pi schema field names exactly.",
+	bash: "Use this Pi tool for shell commands only when file tools are insufficient or command execution is requested. Keep commands scoped and provide a timeout for long-running work.",
+};
+
+export interface ToolBridgeInstructionOptions {
+	availableToolNames?: Iterable<string>;
+}
+
+function normalizeToolNames(names: Iterable<string> | undefined): Set<string> {
+	const fallback = names ?? CORE_TOOL_ORDER;
+	return new Set([...fallback].map((name) => name.toLowerCase()));
+}
+
+function mcpName(name: string): string {
+	return `${MCP_TOOL_PREFIX}${name}`;
+}
+
+function formatToolList(toolNames: Set<string>): string {
+	const ordered = [
+		...CORE_TOOL_ORDER.filter((name) => toolNames.has(name)),
+		...[...toolNames].filter((name) => !CORE_TOOL_ORDER.includes(name as typeof CORE_TOOL_ORDER[number])).sort(),
+	];
+	return ordered.map((name) => `\`${mcpName(name)}\``).join(", ");
+}
+
+export function buildPiToolBridgeInstruction(options: ToolBridgeInstructionOptions = {}): string {
+	const toolNames = normalizeToolNames(options.availableToolNames);
+	const has = (name: string) => toolNames.has(name);
+	const lines = [
+		"Pi Tool Bridge:",
+		`Pi executes tools; CodeBuddy sees available Pi tools through the MCP server \`${MCP_SERVER_NAME}\`.`,
+	];
+
+	if (toolNames.size === 0) {
+		lines.push("No Pi tools are currently available through the bridge. Do not invoke unavailable tools.");
+		return lines.join("\n");
+	}
+
+	lines.push(`Available bridged Pi tools in this turn: ${formatToolList(toolNames)}.`);
+	lines.push("Tool selection rules:");
+
+	if (has("read")) {
+		lines.push(`- Use \`${mcpName("read")}\` to inspect existing repository files before file-specific answers or edits. Prefer it over shelling out to cat/sed for file reads.`);
+	} else {
+		lines.push("- Use available Pi file tools to inspect existing repository files before editing when such tools are present.");
+	}
+	if (has("edit")) {
+		const prefix = has("read") ? `After reading, use \`${mcpName("edit")}\`` : `Use \`${mcpName("edit")}\``;
+		lines.push(`- ${prefix} for targeted changes to existing files. The oldText/old_string value must exactly match existing content.`);
+	}
+	if (has("write")) {
+		const editFallback = has("edit") ? ` prefer \`${mcpName("edit")}\` for targeted changes to existing files.` : " avoid broad replacement of existing files.";
+		lines.push(`- Use \`${mcpName("write")}\` only for new files or deliberate full-file replacement;${editFallback}`);
+	}
+	if (has("bash")) {
+		lines.push(`- Use \`${mcpName("bash")}\` only when file tools are insufficient, for search/test/build/git information, or when command execution is requested.`);
+	}
+	lines.push("Tool arguments must match the Pi tool schema exactly. After a tool result, base the next step on that result; if it is an error, correct the call instead of assuming success.");
+
+	return lines.join("\n");
+}
+
+export function enhancePiToolForCodebuddy<T extends { name: string; description?: string }>(tool: T): T {
+	const guidance = BUILTIN_TOOL_GUIDANCE[tool.name.toLowerCase()];
+	if (!guidance) return tool;
+	if (tool.description?.includes(TOOL_GUIDANCE_MARKER)) return tool;
+	const description = tool.description
+		? `${tool.description}\n\n${TOOL_GUIDANCE_MARKER} ${guidance}`
+		: `${TOOL_GUIDANCE_MARKER} ${guidance}`;
+	return { ...tool, description };
+}
+
+// Extract skills block from pi's system prompt for forwarding to CodeBuddy.
+export function extractSkillsBlock(systemPrompt?: string): string | undefined {
+	if (!systemPrompt) return undefined;
+	const startMarker = SKILLS_START_MARKER;
+	const endMarker = SKILLS_END_MARKER;
+	const start = systemPrompt.indexOf(startMarker);
+	if (start === -1) return undefined;
+	const end = systemPrompt.indexOf(endMarker, start);
+	if (end === -1) return undefined;
+	return rewriteSkillsBlock(systemPrompt.slice(start, end + endMarker.length).trim());
+}
+
+export function rewriteSkillsBlock(skillsBlock: string): string {
+	return skillsBlock.replace(
+		"Use the read tool to load a skill's file",
+		`Use the read tool (mcp__${MCP_SERVER_NAME}__read) to load a skill's file`,
+	);
+}
+
+function stripSkillsBlock(systemPrompt: string): string {
+	const start = systemPrompt.indexOf(SKILLS_START_MARKER);
+	if (start === -1) return systemPrompt;
+	const end = systemPrompt.indexOf(SKILLS_END_MARKER, start);
+	if (end === -1) return systemPrompt;
+	return (systemPrompt.slice(0, start) + systemPrompt.slice(end + SKILLS_END_MARKER.length))
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+}
+
+function applySkillsRewrite(systemPrompt: string): string {
+	const rewritten = extractSkillsBlock(systemPrompt);
+	if (!rewritten) return systemPrompt;
+	const start = systemPrompt.indexOf(SKILLS_START_MARKER);
+	const end = systemPrompt.indexOf(SKILLS_END_MARKER, start);
+	if (start === -1 || end === -1) return systemPrompt;
+	return systemPrompt.slice(0, start) + rewritten + systemPrompt.slice(end + SKILLS_END_MARKER.length);
+}
+
+/** Pi system prompt as CodeBuddy override (replaces default "CodeBuddy Code" identity). */
+export function buildCodebuddySystemPrompt(
+	piSystemPrompt: string | undefined,
+	options?: { includeAgents?: boolean; includeSkills?: boolean; includeToolBridge?: boolean; availableToolNames?: Iterable<string> },
+): string | undefined {
+	const parts: string[] = [];
+	const includeToolBridge = options?.includeToolBridge !== false;
+
+	if (includeToolBridge) {
+		parts.push(buildPiToolBridgeInstruction({ availableToolNames: options?.availableToolNames }));
+	}
+
+	if (piSystemPrompt) {
+		let prompt = piSystemPrompt;
+		if (options?.includeSkills === false) {
+			prompt = stripSkillsBlock(prompt);
+		} else {
+			prompt = includeToolBridge ? applySkillsRewrite(prompt) : prompt;
+		}
+		if (prompt) parts.push(prompt);
+	}
+
+	if (options?.includeAgents !== false) {
+		const agents = extractAgentsAppend();
+		if (agents) parts.push(agents);
+	}
+
+	return parts.length > 0 ? parts.join("\n\n") : undefined;
+}

package/src/typebox-to-zod.ts

@@ -0,0 +1,160 @@
+// TypeBox (JSON Schema) → Zod conversion used by buildMcpServers.
+//
+// Pi tools declare their parameters as TypeBox objects (i.e. JSON Schema at
+// runtime). The Agent SDK's createSdkMcpServer requires Zod — its internal
+// `Z0()` detects Zod via the `~standard` marker or `_def`/`_zod` properties
+// and silently downgrades unrecognized schemas to
+// `{type: "object", properties: {}}`, which leaves the model with no
+// parameter info. This module bridges the two so MCP-exposed pi tools retain
+// their schemas. If this breaks after an SDK update, check whether `Z0()`
+// detection changed or createSdkMcpServer now accepts raw JSON Schema.
+
+import { z } from "zod";
+
+type JsonSchema = Record<string, unknown>;
+type JsonLiteral = string | number | boolean | null;
+
+function withDescription(schema: z.ZodTypeAny, prop: JsonSchema): z.ZodTypeAny {
+	if (typeof prop.description === "string") return schema.describe(prop.description);
+	return schema;
+}
+
+function isJsonLiteral(value: unknown): value is JsonLiteral {
+	return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+
+function literalSchema(value: unknown): z.ZodTypeAny {
+	if (
+		isJsonLiteral(value)
+	) {
+		return z.literal(value);
+	}
+	return z.unknown();
+}
+
+function unionSchema(schemas: z.ZodTypeAny[]): z.ZodTypeAny {
+	if (schemas.length === 0) return z.unknown();
+	if (schemas.length === 1) return schemas[0];
+	return z.union(schemas as [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]]);
+}
+
+function intersectionSchema(schemas: z.ZodTypeAny[]): z.ZodTypeAny {
+	if (schemas.length === 0) return z.unknown();
+	if (schemas.length === 1) return schemas[0];
+	return schemas.slice(1).reduce((left, right) => z.intersection(left, right), schemas[0]);
+}
+
+function objectSchema(prop: JsonSchema): z.ZodTypeAny {
+	const shape = jsonSchemaToZodShape(prop);
+	const additionalPropertiesSchema =
+		prop.additionalProperties && typeof prop.additionalProperties === "object"
+			? jsonSchemaPropertyToZod(prop.additionalProperties as JsonSchema)
+			: undefined;
+	if (Object.keys(shape).length > 0) {
+		const base = z.object(shape);
+		if (prop.additionalProperties === false) return base.strict();
+		if (additionalPropertiesSchema) return base.catchall(additionalPropertiesSchema);
+		return base.passthrough();
+	}
+	if (additionalPropertiesSchema) return z.record(z.string(), additionalPropertiesSchema);
+	if (prop.additionalProperties === false) return z.object({}).strict();
+	return z.record(z.string(), z.unknown());
+}
+
+export function jsonSchemaPropertyToZod(prop: JsonSchema): z.ZodTypeAny {
+	let base: z.ZodTypeAny;
+
+	if (prop.const !== undefined) {
+		base = literalSchema(prop.const);
+		if (prop.nullable === true) base = base.nullable();
+		return withDescription(base, prop);
+	}
+
+	if (Array.isArray(prop.enum)) {
+		base = unionSchema(prop.enum.map((value) => literalSchema(value)));
+		if (prop.nullable === true) base = base.nullable();
+		return withDescription(base, prop);
+	}
+
+	if (Array.isArray(prop.oneOf)) {
+		base = unionSchema(prop.oneOf.map((item) => jsonSchemaPropertyToZod(item as JsonSchema)));
+		if (prop.nullable === true) base = base.nullable();
+		return withDescription(base, prop);
+	}
+
+	if (Array.isArray(prop.anyOf)) {
+		base = unionSchema(prop.anyOf.map((item) => jsonSchemaPropertyToZod(item as JsonSchema)));
+		if (prop.nullable === true) base = base.nullable();
+		return withDescription(base, prop);
+	}
+
+	if (Array.isArray(prop.allOf)) {
+		base = intersectionSchema(prop.allOf.map((item) => jsonSchemaPropertyToZod(item as JsonSchema)));
+		if (prop.nullable === true) base = base.nullable();
+		return withDescription(base, prop);
+	}
+
+	if (Array.isArray(prop.type)) {
+		const allowsNull = prop.type.includes("null");
+		const schemas = prop.type
+			.filter((value): value is string => typeof value === "string" && value !== "null")
+			.map((value) => jsonSchemaPropertyToZod({ ...prop, type: value, nullable: false }));
+		base = unionSchema(schemas);
+		base = allowsNull ? base.nullable() : base;
+		return withDescription(base, prop);
+	}
+
+	const propType = typeof prop.type === "string" ? prop.type : undefined;
+	switch (propType) {
+		case "string":
+			base = z.string();
+			break;
+		case "number":
+		case "integer":
+			base = z.number();
+			break;
+		case "boolean":
+			base = z.boolean();
+			break;
+		case "array":
+			base = prop.items
+				? z.array(jsonSchemaPropertyToZod(prop.items as JsonSchema))
+				: z.array(z.unknown());
+			break;
+		case "object":
+			base = objectSchema(prop);
+			break;
+		case "null":
+			base = z.null();
+			break;
+		default:
+			if (prop.properties) base = objectSchema(prop);
+			else base = z.unknown();
+	}
+
+	if (prop.nullable === true) base = base.nullable();
+	return withDescription(base, prop);
+}
+
+export function jsonSchemaToZodShape(schema: unknown): Record<string, z.ZodTypeAny> {
+	const s = schema as JsonSchema;
+	const objectSchemas = [s, ...(Array.isArray(s?.allOf) ? s.allOf as JsonSchema[] : [])]
+		.filter((item) => item && typeof item === "object" && ((item as JsonSchema).type === "object" || (item as JsonSchema).properties));
+	if (objectSchemas.length === 0) return {};
+
+	const shape: Record<string, z.ZodTypeAny> = {};
+	for (const objectSchemaPart of objectSchemas) {
+		const props = objectSchemaPart.properties as Record<string, JsonSchema> | undefined;
+		if (!props) continue;
+		const required = new Set(Array.isArray(objectSchemaPart.required) ? objectSchemaPart.required as string[] : []);
+		for (const [key, prop] of Object.entries(props)) {
+			const zodProp = jsonSchemaPropertyToZod(prop);
+			shape[key] = required.has(key) ? zodProp : zodProp.optional();
+		}
+	}
+	return shape;
+}
+
+export function jsonSchemaToZodObject(schema: unknown): z.ZodTypeAny {
+	return jsonSchemaPropertyToZod(schema as JsonSchema);
+}