@linxiraos/pi-ai 1.0.0

package/src/utils/schema/spill.ts

@@ -0,0 +1,43 @@
+import type { JsonObject } from "./types";
+
+export type DescriptionSpillFormat = "spill" | "paren";
+
+function formatSpillValue(value: unknown): string {
+	return JSON.stringify(value);
+}
+
+function formatParenValue(value: unknown): string {
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+/**
+ * Demote stripped JSON Schema keywords into a node's `description` so the model
+ * still receives the constraint as natural-language context after the wire
+ * schema drops it.
+ */
+export function spillToDescription(
+	node: JsonObject,
+	entries: ReadonlyArray<readonly [string, unknown]>,
+	format: DescriptionSpillFormat = "spill",
+): void {
+	let spilled: Array<readonly [string, unknown]> | undefined;
+	for (const entry of entries) {
+		if (entry[1] === undefined) continue;
+		if (spilled === undefined) spilled = [];
+		spilled.push(entry);
+	}
+	if (spilled === undefined || spilled.length === 0) return;
+
+	const existing = typeof node.description === "string" ? node.description : "";
+	if (format === "paren") {
+		let suffix = "";
+		for (const [key, value] of spilled) {
+			suffix += ` (${key}: ${formatParenValue(value)})`;
+		}
+		node.description = `${existing}${suffix}`;
+		return;
+	}
+
+	const formatted = `{${spilled.map(([key, value]) => `${key}: ${formatSpillValue(value)}`).join(", ")}}`;
+	node.description = existing ? `${existing}\n\n${formatted}` : formatted;
+}

package/src/utils/schema/stamps.ts

@@ -0,0 +1,109 @@
+/**
+ * Symbol-keyed lazy memoization stamped directly onto the host object.
+ *
+ * Faster than a module-level `WeakMap` in V8/JSC because the symbol slot is
+ * resolved through the object's hidden class instead of a side-table hash
+ * lookup. The slot is defined as a non-enumerable property so the stamp
+ * does not leak through `{...spread}`, `Object.keys`, `JSON.stringify`, or
+ * `toEqual`-style deep equality.
+ *
+ * Caveats: the stamp lives as long as the host object, even after callers
+ * release their references to the cached value — only use this for caches
+ * whose lifetime should match the host. Frozen hosts cannot be stamped;
+ * `define` silently skips them, so memoization/visit-tracking degrades to
+ * best-effort (recompute on every call, no cycle protection) instead of
+ * throwing.
+ */
+function define<T extends object>(target: T, key: symbol, value: unknown): void {
+	if (Object.isFrozen(target)) return;
+	Object.defineProperty(target, key, { value, writable: true, configurable: true });
+}
+
+export function stamp<T extends object, V>(target: T, key: symbol, compute: (target: T) => V): V {
+	const slot = target as Record<symbol, V | undefined>;
+	const existing = slot[key];
+	if (existing !== undefined) return existing;
+	const value = compute(target);
+	define(target, key, value);
+	return value;
+}
+
+/**
+ * Epoch-keyed cycle guard. Cheaper than `WeakSet` for recursive traversal
+ * because the marker is a single property slot on the host object, written
+ * once and overwritten in place on every subsequent traversal — the hidden
+ * class transitions once per object lifetime, not per traversal.
+ *
+ * Usage:
+ *   function walk(node, epoch = epochNext()) {
+ *     if (!once(node, epoch)) return; // cycle
+ *     for (const child of node.children) walk(child, epoch);
+ *   }
+ */
+const kEpoch = Symbol("pi.schema.epoch");
+let __epoch = 0;
+
+export function epochNext(): number {
+	return ++__epoch;
+}
+
+/**
+ * Marks `target` as visited for this `epoch`. Returns `true` the first time
+ * it is called for a given (target, epoch) pair and `false` on every
+ * subsequent call within the same epoch.
+ */
+export function once<T extends object>(target: T, epoch: number): boolean {
+	const slot = target as Record<symbol, number | undefined>;
+	const cur = slot[kEpoch];
+	if (cur !== undefined && cur >= epoch) return false;
+	if (cur === undefined) define(target, kEpoch, epoch);
+	else slot[kEpoch] = epoch;
+	return true;
+}
+
+/**
+ * Counter-based path tracker. Use when a traversal needs to distinguish
+ * "currently on the recursion path" from "previously visited" — i.e. cycle
+ * detection that throws while still allowing DAG sharing. Increment on
+ * entry, decrement on exit; the slot returns to 0 after a balanced walk so
+ * subsequent top-level calls see a fresh state without any reset.
+ *
+ * Unlike a `WeakSet` with `seen.delete(...)`, the property is never deleted
+ * — only incremented and decremented — so the host object's hidden class
+ * is never invalidated.
+ *
+ * Usage:
+ *   function walk(node) {
+ *     if (!enter(node)) throw new Error("cycle");
+ *     try { for (const c of node.children) walk(c); }
+ *     finally { exit(node); }
+ *   }
+ */
+const kDepth = Symbol("pi.schema.depth");
+
+/**
+ * Returns `true` on first entry, `false` if `target` is already on the
+ * current path. A `false` return does NOT deepen the counter — callers pair
+ * `exit` only with successful enters (`if (!enter(n)) bail; try {…} finally
+ * { exit(n); }`), so incrementing on the cycle branch would leak depth and
+ * make every later top-level walk of the same object misreport a cycle.
+ */
+export function enter<T extends object>(target: T): boolean {
+	const slot = target as Record<symbol, number | undefined>;
+	const cur = slot[kDepth];
+	if (cur === undefined) {
+		define(target, kDepth, 1);
+		return true;
+	}
+	if (cur !== 0) return false;
+	slot[kDepth] = 1;
+	return true;
+}
+
+export function exit<T extends object>(target: T): void {
+	const slot = target as Record<symbol, number | undefined>;
+	const cur = slot[kDepth];
+	// Frozen targets never received the kDepth stamp in `enter` — nothing to unwind.
+	if (cur === undefined) return;
+	slot[kDepth] = cur - 1;
+}

package/src/utils/schema/strict-tool-validation.ts

@@ -0,0 +1,117 @@
+/**
+ * Detects tool-parameter schemas that pass structural JSON-Schema validation
+ * (so {@link isValidJsonSchema} accepts them) yet make OpenAI-style providers
+ * reject the whole request with HTTP 400 — namely an `enum`/`const` whose
+ * value(s) cannot satisfy the node's declared `type`. MCP servers emit these
+ * when a nullable/array branch is built incorrectly (e.g. a non-null `enum`
+ * copied onto a `type: "null"` branch, or an `enum` placed on an `array`
+ * schema instead of its `items`). One such tool 400s the entire turn, so
+ * callers quarantine just the offending tool. See issue #2652.
+ */
+
+type JsonRecord = Record<string, unknown>;
+
+const SCHEMA_TYPE_NAMES: Record<string, true> = {
+	string: true,
+	number: true,
+	integer: true,
+	boolean: true,
+	object: true,
+	array: true,
+	null: true,
+};
+
+function jsonValueMatchesType(value: unknown, type: string): boolean {
+	switch (type) {
+		case "string":
+			return typeof value === "string";
+		case "number":
+			return typeof value === "number";
+		case "integer":
+			return typeof value === "number" && Number.isInteger(value);
+		case "boolean":
+			return typeof value === "boolean";
+		case "null":
+			return value === null;
+		case "object":
+			return typeof value === "object" && value !== null && !Array.isArray(value);
+		case "array":
+			return Array.isArray(value);
+		default:
+			// Unknown type keyword — don't flag (forward compatibility).
+			return true;
+	}
+}
+
+function declaredTypes(node: JsonRecord): string[] {
+	const t = node.type;
+	if (typeof t === "string") return t in SCHEMA_TYPE_NAMES ? [t] : [];
+	if (Array.isArray(t)) return t.filter((x): x is string => typeof x === "string" && x in SCHEMA_TYPE_NAMES);
+	return [];
+}
+
+const CHILD_MAP_KEYS = ["properties", "patternProperties", "$defs", "definitions", "dependentSchemas"] as const;
+const CHILD_SCHEMA_KEYS = [
+	"items",
+	"contains",
+	"not",
+	"if",
+	"then",
+	"else",
+	"propertyNames",
+	"additionalProperties",
+	"unevaluatedProperties",
+	"unevaluatedItems",
+] as const;
+const CHILD_ARRAY_KEYS = ["anyOf", "oneOf", "allOf", "prefixItems"] as const;
+
+/**
+ * Walk a tool parameter schema for OpenAI-strict `enum`/`const`-vs-`type`
+ * contradictions. Returns a JSON-pointer-ish path to the first offending node,
+ * or `null` when the schema is safe to emit.
+ */
+export function findStrictToolSchemaViolation(schema: unknown, path = "#"): string | null {
+	if (Array.isArray(schema)) {
+		for (let i = 0; i < schema.length; i++) {
+			const hit = findStrictToolSchemaViolation(schema[i], `${path}/${i}`);
+			if (hit) return hit;
+		}
+		return null;
+	}
+	if (typeof schema !== "object" || schema === null) return null;
+	const node = schema as JsonRecord;
+
+	const types = declaredTypes(node);
+	if (types.length > 0) {
+		if (Array.isArray(node.enum) && node.enum.some(v => !types.some(t => jsonValueMatchesType(v, t)))) {
+			return `${path}/enum`;
+		}
+		if ("const" in node && !types.some(t => jsonValueMatchesType(node.const, t))) {
+			return `${path}/const`;
+		}
+	}
+
+	for (const key of CHILD_MAP_KEYS) {
+		const sub = node[key];
+		if (sub && typeof sub === "object" && !Array.isArray(sub)) {
+			for (const k of Object.keys(sub as JsonRecord)) {
+				const hit = findStrictToolSchemaViolation((sub as JsonRecord)[k], `${path}/${key}/${k}`);
+				if (hit) return hit;
+			}
+		}
+	}
+	for (const key of CHILD_SCHEMA_KEYS) {
+		if (key in node) {
+			const hit = findStrictToolSchemaViolation(node[key], `${path}/${key}`);
+			if (hit) return hit;
+		}
+	}
+	for (const key of CHILD_ARRAY_KEYS) {
+		const arr = node[key];
+		if (Array.isArray(arr)) {
+			const hit = findStrictToolSchemaViolation(arr, `${path}/${key}`);
+			if (hit) return hit;
+		}
+	}
+	return null;
+}

package/src/utils/schema/types.ts

@@ -0,0 +1,10 @@
+export type JsonObject = Record<string, unknown>;
+
+export function isJsonObject(value: unknown): value is JsonObject {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** True when `value` is a plain JSON object with no own enumerable keys. */
+export function isJsonObjectEmpty(value: JsonObject): boolean {
+	return Object.keys(value).length === 0;
+}

package/src/utils/schema/typescript.ts

@@ -0,0 +1,212 @@
+/**
+ * Render a JSON Schema as a simplified, human-readable TypeScript type.
+ *
+ * This is a *display* conversion, not a faithful TS codegen: it surfaces the
+ * shape (objects, arrays, unions, enums, records) and property descriptions so
+ * a model — or a human reading `/dump` — can grasp a tool's parameters at a
+ * glance, far more legibly than raw JSON Schema. Refinement keywords
+ * (min/max/pattern/format) are intentionally dropped; only type structure,
+ * literal enums/consts, and descriptions survive.
+ */
+
+import { isJsonObject } from "./types";
+
+export interface JsonSchemaToTsOptions {
+	/** Indentation unit for nested object bodies. Default two spaces (none in `harmony` style). */
+	readonly indent?: string;
+	/** Emit `description` keywords as comments on object properties. Default true. */
+	readonly comments?: boolean;
+	/**
+	 * Output flavor. `default` renders JSDoc comments, `;` delimiters, and
+	 * indented bodies; `harmony` renders the flat OpenAI-Harmony convention —
+	 * `//` line comments, `,` delimiters, no indentation.
+	 */
+	readonly style?: "default" | "harmony";
+}
+
+interface Ctx {
+	readonly indent: string;
+	readonly comments: boolean;
+	readonly harmony: boolean;
+	readonly defs: Record<string, unknown> | undefined;
+	readonly seen: Set<unknown>;
+}
+
+const SAFE_KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const LOCAL_REF = /^#\/(?:\$defs|definitions)\/(.+)$/;
+/** Inline an array item as `T[]` only while it stays a short single token. */
+const INLINE_ARRAY_LIMIT = 40;
+
+function literal(value: unknown): string {
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+	return JSON.stringify(value) ?? "unknown";
+}
+
+/** Join member types into a TS union, deduping structurally identical renders. */
+function joinUnion(parts: readonly string[]): string {
+	const seen = new Set<string>();
+	const unique: string[] = [];
+	for (const part of parts) {
+		if (seen.has(part)) continue;
+		seen.add(part);
+		unique.push(part);
+	}
+	return unique.length > 0 ? unique.join(" | ") : "never";
+}
+
+function emitDescription(lines: string[], description: string, ctx: Ctx, pad: string): void {
+	if (ctx.harmony) {
+		for (const line of description.split("\n")) lines.push(`${pad}// ${line}`.trimEnd());
+		return;
+	}
+	// `* /` keeps a stray closing token inside the description from ending the comment.
+	const safe = description.replace(/\*\//g, "* /");
+	if (!safe.includes("\n")) {
+		lines.push(`${pad}/** ${safe} */`);
+		return;
+	}
+	lines.push(`${pad}/**`);
+	for (const line of safe.split("\n")) lines.push(`${pad} * ${line}`);
+	lines.push(`${pad} */`);
+}
+
+function convertArray(node: Record<string, unknown>, ctx: Ctx, pad: string): string {
+	const prefixItems = node.prefixItems;
+	if (Array.isArray(prefixItems)) {
+		return `[${prefixItems.map(item => convert(item, ctx, pad)).join(", ")}]`;
+	}
+	const items = node.items;
+	if (items === undefined || items === true) return "unknown[]";
+	if (items === false) return "never[]";
+	const inner = convert(items, ctx, pad);
+	if (inner.includes("\n") || inner.includes(" | ") || inner.length > INLINE_ARRAY_LIMIT) {
+		return `Array<${inner}>`;
+	}
+	return `${inner}[]`;
+}
+
+function convertObject(node: Record<string, unknown>, ctx: Ctx, pad: string): string {
+	const properties = isJsonObject(node.properties) ? node.properties : undefined;
+	const additional = node.additionalProperties;
+	const childPad = pad + ctx.indent;
+
+	const body: string[] = [];
+	if (properties) {
+		const required = new Set(
+			Array.isArray(node.required) ? node.required.filter((key): key is string => typeof key === "string") : [],
+		);
+		const delimiter = ctx.harmony ? "," : ";";
+		for (const key in properties) {
+			const value = properties[key];
+			if (
+				ctx.comments &&
+				isJsonObject(value) &&
+				typeof value.description === "string" &&
+				value.description.length > 0
+			) {
+				emitDescription(body, value.description, ctx, childPad);
+			}
+			const optional = required.has(key) ? "" : "?";
+			const name = SAFE_KEY.test(key) ? key : JSON.stringify(key);
+			body.push(`${childPad}${name}${optional}: ${convert(value, ctx, childPad)}${delimiter}`);
+		}
+	}
+
+	// No named properties: pure record / open / empty object.
+	if (body.length === 0) {
+		if (isJsonObject(additional)) return `Record<string, ${convert(additional, ctx, pad)}>`;
+		if (additional === true) return "Record<string, unknown>";
+		return "{}";
+	}
+
+	// Named properties alongside a free-form value schema → index signature.
+	if (isJsonObject(additional)) {
+		body.push(`${childPad}[key: string]: ${convert(additional, ctx, childPad)}${ctx.harmony ? "," : ";"}`);
+	}
+	return `{\n${body.join("\n")}\n${pad}}`;
+}
+
+function convertType(type: string, node: Record<string, unknown>, ctx: Ctx, pad: string): string {
+	switch (type) {
+		case "string":
+			return "string";
+		case "integer":
+		case "number":
+			return "number";
+		case "boolean":
+			return "boolean";
+		case "null":
+			return "null";
+		case "array":
+			return convertArray(node, ctx, pad);
+		case "object":
+			return convertObject(node, ctx, pad);
+		default:
+			return "unknown";
+	}
+}
+
+function convert(node: unknown, ctx: Ctx, pad: string): string {
+	if (node === true) return "unknown";
+	if (node === false) return "never";
+	if (!isJsonObject(node)) return "unknown";
+
+	const ref = node.$ref;
+	if (typeof ref === "string") {
+		const match = LOCAL_REF.exec(ref);
+		const resolved = match && ctx.defs ? ctx.defs[match[1]] : undefined;
+		if (isJsonObject(resolved) && !ctx.seen.has(resolved)) {
+			ctx.seen.add(resolved);
+			const out = convert(resolved, ctx, pad);
+			ctx.seen.delete(resolved);
+			return out;
+		}
+		return ref.slice(ref.lastIndexOf("/") + 1);
+	}
+
+	if ("const" in node) return literal(node.const);
+
+	if (Array.isArray(node.enum)) {
+		return node.enum.length > 0 ? joinUnion(node.enum.map(literal)) : "never";
+	}
+
+	const union = Array.isArray(node.anyOf) ? node.anyOf : Array.isArray(node.oneOf) ? node.oneOf : undefined;
+	if (union) return joinUnion(union.map(variant => convert(variant, ctx, pad)));
+
+	if (Array.isArray(node.allOf)) {
+		return node.allOf.map(variant => convert(variant, ctx, pad)).join(" & ");
+	}
+
+	const type = node.type;
+	if (Array.isArray(type)) {
+		return joinUnion(type.map(entry => convertType(String(entry), node, ctx, pad)));
+	}
+	if (typeof type === "string") return convertType(type, node, ctx, pad);
+
+	return "unknown";
+}
+
+/** Convert a JSON Schema object into a simplified TypeScript type string. */
+export function jsonSchemaToTypeScript(schema: unknown, options?: JsonSchemaToTsOptions): string {
+	const root = isJsonObject(schema) ? schema : undefined;
+	let defs: Record<string, unknown> | undefined;
+	if (root) {
+		for (const key of ["definitions", "$defs"] as const) {
+			const value = root[key];
+			if (isJsonObject(value)) {
+				defs ??= {};
+				Object.assign(defs, value);
+			}
+		}
+	}
+	const harmony = options?.style === "harmony";
+	const ctx: Ctx = {
+		indent: options?.indent ?? (harmony ? "" : "  "),
+		comments: options?.comments ?? true,
+		harmony,
+		defs,
+		seen: new Set(),
+	};
+	return convert(schema, ctx, "");
+}