Squash merge of https://github.com/morluto/rea/pull/1749. Co-authored-by: akushonkamen <akushonkamen@163.com> Co-authored-by: GLM <noreply@z.ai>
306 lines
10 KiB
TypeScript
306 lines
10 KiB
TypeScript
import { isDeepStrictEqual } from "node:util";
|
|
|
|
export const schemaMaps = new Set([
|
|
"$defs",
|
|
"definitions",
|
|
"properties",
|
|
"patternProperties",
|
|
"dependentSchemas",
|
|
"dependencies",
|
|
]);
|
|
export const schemaArrays = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
|
|
export const schemaChildren = new Set([
|
|
"items",
|
|
"additionalItems",
|
|
"contains",
|
|
"additionalProperties",
|
|
"unevaluatedProperties",
|
|
"unevaluatedItems",
|
|
"propertyNames",
|
|
"not",
|
|
"if",
|
|
"then",
|
|
"else",
|
|
]);
|
|
|
|
const isObject = (value: unknown): value is Readonly<Record<string, unknown>> =>
|
|
typeof value === "object" && value !== null && !Array.isArray(value);
|
|
|
|
const resolveReference = (
|
|
root: Readonly<Record<string, unknown>>,
|
|
reference: string,
|
|
): unknown => {
|
|
if (reference === "#") return root;
|
|
if (!reference.startsWith("#/")) return undefined;
|
|
let value: unknown = root;
|
|
for (const token of reference.slice(2).split("/")) {
|
|
const key = token.replaceAll("~1", "/").replaceAll("~0", "~");
|
|
if (!isObject(value) || !Object.hasOwn(value, key)) return undefined;
|
|
value = value[key];
|
|
}
|
|
return value;
|
|
};
|
|
|
|
const referencedDescription = (
|
|
root: Readonly<Record<string, unknown>>,
|
|
schema: Readonly<Record<string, unknown>>,
|
|
): string | undefined => {
|
|
let value: unknown = schema;
|
|
const active = new Set<string>();
|
|
while (isObject(value)) {
|
|
if (typeof value.description === "string") return value.description;
|
|
if (typeof value.$ref !== "string" || active.has(value.$ref))
|
|
return undefined;
|
|
active.add(value.$ref);
|
|
value = resolveReference(root, value.$ref);
|
|
}
|
|
return undefined;
|
|
};
|
|
|
|
const describeSchema = (
|
|
schema: unknown,
|
|
root: Readonly<Record<string, unknown>>,
|
|
describeProperty: (property: string) => string | undefined,
|
|
): unknown => {
|
|
if (!isObject(schema)) return schema;
|
|
return Object.fromEntries(
|
|
Object.entries(schema).map(([key, value]) => {
|
|
if (schemaMaps.has(key) && isObject(value))
|
|
return [
|
|
key,
|
|
Object.fromEntries(
|
|
Object.entries(value).map(([name, child]) => {
|
|
const described = describeSchema(child, root, describeProperty);
|
|
if (key !== "properties" || !isObject(described))
|
|
return [name, described];
|
|
const description =
|
|
referencedDescription(root, described) ??
|
|
describeProperty(name);
|
|
return [
|
|
name,
|
|
description === undefined
|
|
? described
|
|
: { ...described, description },
|
|
];
|
|
}),
|
|
),
|
|
];
|
|
if (schemaArrays.has(key) && Array.isArray(value))
|
|
return [
|
|
key,
|
|
value.map((child) => describeSchema(child, root, describeProperty)),
|
|
];
|
|
if (schemaChildren.has(key))
|
|
return [
|
|
key,
|
|
Array.isArray(value)
|
|
? value.map((child) =>
|
|
describeSchema(child, root, describeProperty),
|
|
)
|
|
: describeSchema(value, root, describeProperty),
|
|
];
|
|
// Annotation values and literal const/enum data are not schemas.
|
|
return [key, value];
|
|
}),
|
|
);
|
|
};
|
|
|
|
const objectBranch = (
|
|
root: Readonly<Record<string, unknown>>,
|
|
branch: unknown,
|
|
): Readonly<Record<string, unknown>> | undefined => {
|
|
// Reference siblings evaluate separately from the target in 2020-12, so a
|
|
// merged object could accept inputs the branch rejects.
|
|
const resolved =
|
|
isObject(branch) && typeof branch.$ref === "string"
|
|
? Object.keys(branch).length === 1
|
|
? resolveReference(root, branch.$ref)
|
|
: undefined
|
|
: branch;
|
|
return isObject(resolved) &&
|
|
resolved.type === "object" &&
|
|
isObject(resolved.properties)
|
|
? resolved
|
|
: undefined;
|
|
};
|
|
|
|
const requiredProperties = (
|
|
branch: Readonly<Record<string, unknown>>,
|
|
): readonly string[] =>
|
|
Array.isArray(branch.required)
|
|
? branch.required.filter((name) => typeof name === "string")
|
|
: [];
|
|
|
|
const sharedRequiredProperties = (
|
|
branches: readonly Readonly<Record<string, unknown>>[],
|
|
): readonly string[] => {
|
|
const [first = [], ...others] = branches.map(requiredProperties);
|
|
return first.filter((name) => others.every((names) => names.includes(name)));
|
|
};
|
|
|
|
const inputGroup = (branch: Readonly<Record<string, unknown>>): string => {
|
|
const required = requiredProperties(branch);
|
|
const optional = Object.keys(branch.properties ?? {})
|
|
.filter((name) => !required.includes(name))
|
|
.map((name) => `[${name}]`);
|
|
return [...required, ...optional].join(" + ");
|
|
};
|
|
|
|
// Anthropic tool input schemas reject anyOf, oneOf, and allOf at the root, and
|
|
// clients then drop the tool or advertise it without parameters. Present a
|
|
// root union of strict object groups as one object whose properties are the
|
|
// union of the groups. The canonical Zod schema still enforces the exact group.
|
|
const flattenRootObjectUnion = (
|
|
root: Record<string, unknown>,
|
|
): Record<string, unknown> => {
|
|
const { anyOf, oneOf, ...rest } = root;
|
|
const alternatives = Array.isArray(anyOf) ? anyOf : oneOf;
|
|
if (
|
|
!Array.isArray(alternatives) ||
|
|
alternatives.length === 0 ||
|
|
root.properties !== undefined
|
|
)
|
|
return root;
|
|
const branches = alternatives.map((branch) => objectBranch(root, branch));
|
|
if (!branches.every((branch) => branch !== undefined)) return root;
|
|
const variants = new Map<string, unknown[]>();
|
|
for (const branch of branches)
|
|
for (const [name, schema] of Object.entries(branch.properties ?? {})) {
|
|
const known = variants.get(name) ?? [];
|
|
if (!known.some((seen) => isDeepStrictEqual(seen, schema)))
|
|
known.push(schema);
|
|
variants.set(name, known);
|
|
}
|
|
const required = sharedRequiredProperties(branches);
|
|
// A field unique to a group still needs that group's required partners.
|
|
// Counting properties alone would let optional fields pad an incomplete pair.
|
|
const dependencies = Object.fromEntries(
|
|
[...variants.keys()].flatMap((name) => {
|
|
const owners = branches.filter((branch) =>
|
|
Object.hasOwn(branch.properties ?? {}, name),
|
|
);
|
|
const partners = sharedRequiredProperties(owners).filter(
|
|
(partner) => partner !== name && !required.includes(partner),
|
|
);
|
|
return partners.length > 0 ? [[name, partners]] : [];
|
|
}),
|
|
);
|
|
const fewestRequired = Math.min(
|
|
...branches.map((branch) => requiredProperties(branch).length),
|
|
);
|
|
// Groups that differ only in property values add no caller guidance.
|
|
const groups = [...new Set(branches.map(inputGroup))];
|
|
const description = [
|
|
typeof rest.description === "string" ? rest.description : undefined,
|
|
groups.length > 1
|
|
? `Provide a complete input group: ${groups.join("; ")}.`
|
|
: undefined,
|
|
].filter((text) => text !== undefined);
|
|
return {
|
|
...rest,
|
|
type: "object",
|
|
...(description.length > 0 ? { description: description.join(" ") } : {}),
|
|
properties: Object.fromEntries(
|
|
[...variants].map(([name, schemas]) => [
|
|
name,
|
|
schemas.length === 1 ? schemas[0] : { anyOf: schemas },
|
|
]),
|
|
),
|
|
...(required.length > 0 ? { required } : {}),
|
|
...(fewestRequired > 0 ? { minProperties: fewestRequired } : {}),
|
|
...(Object.keys(dependencies).length > 0
|
|
? {
|
|
[root.$schema === "http://json-schema.org/draft-07/schema#"
|
|
? "dependencies"
|
|
: "dependentRequired"]: dependencies,
|
|
}
|
|
: {}),
|
|
...(branches.every((branch) => branch.additionalProperties === false)
|
|
? { additionalProperties: false }
|
|
: {}),
|
|
};
|
|
};
|
|
|
|
/** Describe canonical input fields and present the root as one object. */
|
|
export const presentInputJsonSchema = (
|
|
root: Record<string, unknown>,
|
|
describeProperty: (property: string) => string | undefined,
|
|
): Record<string, unknown> => {
|
|
const flattened = flattenRootObjectUnion(root);
|
|
const described = describeSchema(flattened, flattened, describeProperty);
|
|
return isObject(described) ? described : flattened;
|
|
};
|
|
|
|
/**
|
|
* Clients that render advertised inputs into SDK declarations expand
|
|
* schema-local references with a shared per-input budget: Pi 1.1.0 code-mode
|
|
* allows 32 expansions and degrades every later reference to `unknown`
|
|
* (morluto/rea#1632), hiding the fields those references describe. The budget
|
|
* counts conservatively — every resolvable, non-cyclic reference occurrence
|
|
* in every schema position — so any reference-resolving client stays within
|
|
* its measured limit.
|
|
*/
|
|
export const advertisedReferenceExpansionBudget = 32;
|
|
|
|
const definitionKeys = new Set(["$defs", "definitions"]);
|
|
|
|
const countReferenceExpansions = (
|
|
node: unknown,
|
|
root: Readonly<Record<string, unknown>>,
|
|
active: ReadonlySet<string>,
|
|
count: { value: number },
|
|
): void => {
|
|
if (Array.isArray(node)) {
|
|
node.forEach((child) =>
|
|
countReferenceExpansions(child, root, active, count),
|
|
);
|
|
return;
|
|
}
|
|
if (!isObject(node)) return;
|
|
if (typeof node.$ref === "string" && !active.has(node.$ref)) {
|
|
const target = resolveReference(root, node.$ref);
|
|
if (target !== undefined) {
|
|
count.value += 1;
|
|
countReferenceExpansions(
|
|
target,
|
|
root,
|
|
new Set([...active, node.$ref]),
|
|
count,
|
|
);
|
|
return;
|
|
}
|
|
}
|
|
for (const [key, value] of Object.entries(node)) {
|
|
if (definitionKeys.has(key)) continue;
|
|
if (schemaMaps.has(key) && isObject(value)) {
|
|
for (const child of Object.values(value))
|
|
countReferenceExpansions(child, root, active, count);
|
|
} else if (schemaArrays.has(key) || schemaChildren.has(key)) {
|
|
countReferenceExpansions(value, root, active, count);
|
|
}
|
|
}
|
|
};
|
|
|
|
/** Conservative client expansion count over every schema position. */
|
|
export const countLocalReferenceExpansions = (
|
|
schema: Record<string, unknown>,
|
|
): number => {
|
|
const count = { value: 0 };
|
|
countReferenceExpansions(schema, schema, new Set(), count);
|
|
return count.value;
|
|
};
|
|
|
|
/**
|
|
* Keep the shared-definition form of an advertised input while clients can
|
|
* still resolve it. Once rendering would exhaust the reference budget, fall
|
|
* back to the inline projection, which carries no shared definitions for the
|
|
* nonrecursive schemas this repository advertises, so every field renders
|
|
* with complete structure in every reference-resolving client.
|
|
*/
|
|
export const inputSchemaWithinReferenceExpansionBudget = (
|
|
shared: Record<string, unknown>,
|
|
inline: () => Record<string, unknown>,
|
|
budget: number,
|
|
): Record<string, unknown> =>
|
|
countLocalReferenceExpansions(shared) <= budget ? shared : inline();
|