Files
reverse-engineering-anything/src/contracts/advertisedDialectProjection.ts
T
morluto b0e0d52a9f refactor(mcp): leave input literal portability to the advertised dialect projection (#11207)
* refactor(mcp): leave input literal portability to the advertised dialect projection

* test(mcp): leave listed-input literal portability to the dialect check

* test(mcp): trigger normalization dependency cases with non-portable patterns

* refactor(mcp): let the dialect projection own input patterns and dependency prose (#11238)

* refactor(mcp): let the dialect projection own input patterns and dependency prose

* refactor(mcp): drop the unused import from the output schema presentation

* test(mcp): force the reduced form by depth now that the projection re-emits patterns

* test(mcp): take advertised input from the one advertised-tool owner after #11268

* test(mcp): check the base64 pad-bit widening on the advertised input, not the registered one
2026-11-16 03:55:27 +08:00

430 lines
16 KiB
TypeScript

import { isDeepStrictEqual } from "node:util";
import { isRecord } from "../domain/isRecord.js";
import {
ADVERTISED_BOUND_LIMIT,
ADVERTISED_DESCRIPTION_MAX_CHARACTERS,
} from "./advertisedDialect.js";
import { projectPortablePattern } from "./portablePattern.js";
// The one projection from a self-contained (reference-free) input schema into
// the portable advertised dialect declared in `advertisedDialect.ts`. Every
// rewrite is exact or widening: a canonical-valid input always satisfies the
// projection, and the server still validates the canonical contract. A
// constraint the dialect cannot express leaves the schema; when an agent needs
// it to build a valid call, a sentence joins the tool description instead.
// Codex strips every description inside a schema above 5,000 bytes and Zed
// drops the root description, so that guidance never lives in the schema.
type Schema = Record<string, unknown>;
/** A schema in the portable dialect, plus guidance for the tool description. */
export interface AdvertisedDialectProjection {
readonly schema: Schema;
/** The root description, then sentences for constraints the schema omits. */
readonly guidance: readonly string[];
}
const isStringList = (value: unknown): value is readonly string[] =>
Array.isArray(value) && value.every((item) => typeof item === "string");
const literalType = (value: unknown): string | undefined => {
if (typeof value === "string") return "string";
if (typeof value === "boolean") return "boolean";
if (typeof value === "number")
return Number.isInteger(value) ? "integer" : "number";
return undefined;
};
/** One type covering every literal, or undefined when none does. */
const literalsType = (values: readonly unknown[]): string | undefined => {
const types = new Set(values.map(literalType));
if (types.has(undefined)) return undefined;
if (types.size === 1) return [...types][0];
return types.size === 2 && types.has("integer") && types.has("number")
? "number"
: undefined;
};
/** Sentences for `dependentRequired` and string-list `dependencies`. */
export const dependencyGuidance = (
schema: Readonly<Record<string, unknown>>,
): readonly string[] => {
const dependencies = isRecord(schema.dependentRequired)
? schema.dependentRequired
: isRecord(schema.dependencies)
? schema.dependencies
: {};
return Object.entries(dependencies).flatMap(([property, partners]) =>
isStringList(partners) && partners.length > 0
? [
`When ${property} is provided, also provide ${partners.join(" and ")}.`,
]
: [],
);
};
const truncatedDescription = (text: string): string => {
if (text.length <= ADVERTISED_DESCRIPTION_MAX_CHARACTERS) return text;
let kept = text.slice(0, ADVERTISED_DESCRIPTION_MAX_CHARACTERS - 1);
const last = kept.charCodeAt(kept.length - 1);
if (last >= 0xd800 && last <= 0xdbff) kept = kept.slice(0, -1);
return `${kept}…`;
};
/**
* Hoist `allOf` members into their parent. A keyword the parent already sets
* differently is dropped, which only widens the advertisement; required names
* are a conjunction, so their union is exact.
*/
const mergeAllOf = (schema: Schema): Schema => {
if (!Array.isArray(schema.allOf)) return schema;
const { allOf, ...merged } = schema;
const tails = new Map<string, Schema>();
for (const key of TUPLE_TAIL_KEYS)
if (isTupleTail(merged, key)) tails.set(key, merged);
for (const member of allOf) {
if (!isRecord(member)) continue;
const flattened = mergeAllOf(member);
for (const [key, value] of Object.entries(flattened)) {
if (!Object.hasOwn(merged, key)) {
merged[key] = value;
if (isTupleTail(flattened, key)) tails.set(key, flattened);
} else if (key === "required" && isStringList(merged.required)) {
if (isStringList(value))
merged.required = [...new Set([...merged.required, ...value])];
}
}
}
// A closed object's properties and patterns are scoped to its own schema
// object. Hoisting its closure beside another member's properties can
// reject names accepted by the original conjunction.
delete merged.additionalProperties;
// A tuple tail applies past its own object's positions. Beside a different
// number of positions it would constrain elements the original did not.
for (const [key, owner] of tails)
if (tuplePositions(owner)?.length !== tuplePositions(merged)?.length)
delete merged[key];
return merged;
};
/** Keywords that constrain only the elements past a tuple's positions. */
const TUPLE_TAIL_KEYS = ["items", "additionalItems"] as const;
/** Positional element schemas (2020-12 `prefixItems` or draft-07 `items`). */
const tuplePositions = (schema: Schema): readonly unknown[] | undefined =>
Array.isArray(schema.prefixItems)
? schema.prefixItems
: Array.isArray(schema.items)
? schema.items
: undefined;
/** Whether `key` constrains only the elements past `schema`'s positions. */
const isTupleTail = (schema: Schema, key: string): boolean =>
(key === "additionalItems" && Array.isArray(schema.items)) ||
(key === "items" &&
Array.isArray(schema.prefixItems) &&
!Array.isArray(schema.items));
const branchType = (branch: unknown): string | undefined =>
isRecord(branch) && typeof branch.type === "string" ? branch.type : undefined;
const onlyKeys = (schema: Schema, keys: readonly string[]): boolean =>
Object.keys(schema).every((key) => keys.includes(key));
const distinct = (schemas: readonly unknown[]): unknown[] => {
const kept: unknown[] = [];
for (const schema of schemas)
if (!kept.some((known) => isDeepStrictEqual(known, schema)))
kept.push(schema);
return kept;
};
const label = (path: string): string =>
path === "" ? "The input" : `\`${path}\``;
/** Exclusive numeric bounds become inclusive: exact for integers. */
const inclusiveBounds = (source: Schema, out: Schema): void => {
const { type } = source;
const integral =
type === "integer" ||
(isStringList(type) &&
type.includes("integer") &&
!type.includes("number"));
let { minimum, maximum } = source;
if (typeof source.exclusiveMinimum === "number") {
const lower = integral
? Math.floor(source.exclusiveMinimum) + 1
: source.exclusiveMinimum;
minimum = typeof minimum === "number" ? Math.max(minimum, lower) : lower;
}
if (typeof source.exclusiveMaximum === "number") {
const upper = integral
? Math.ceil(source.exclusiveMaximum) - 1
: source.exclusiveMaximum;
maximum = typeof maximum === "number" ? Math.min(maximum, upper) : upper;
}
if (typeof minimum === "number") out.minimum = minimum;
if (typeof maximum === "number") out.maximum = maximum;
};
/** Length and item bounds clients can compile, and the portable pattern. */
const scalarBounds = (source: Schema, out: Schema): void => {
for (const bound of ["minLength", "maxLength", "minItems", "maxItems"])
if (
Number.isSafeInteger(source[bound]) &&
(source[bound] as number) < ADVERTISED_BOUND_LIMIT
)
out[bound] = source[bound];
if (typeof source.pattern === "string") {
const projected = projectPortablePattern(source.pattern);
if (projected.kind !== "unexpressible") out.pattern = projected.pattern;
}
inclusiveBounds(source, out);
};
/** Only non-empty string enums are portable; other literals keep a type. */
const literalKeywords = (source: Schema, out: Schema): void => {
const literals = Object.hasOwn(source, "const")
? [source.const]
: Array.isArray(source.enum) && source.enum.length > 0
? source.enum
: undefined;
if (literals === undefined) return;
const literal = literalsType(literals);
if (
literal === "string" &&
!literals.includes("") &&
(out.type === undefined || out.type === "string")
) {
out.type = "string";
out.enum = [...new Set(literals)];
} else if (literal !== undefined && out.type === undefined)
out.type = literal;
};
const isStringEnum = (branch: unknown): branch is Schema =>
isRecord(branch) &&
branch.type === "string" &&
Array.isArray(branch.enum) &&
onlyKeys(branch, ["type", "enum", "description"]);
/** `[T, "null"]` becomes the single nullable form: a typed branch or null. */
const nullableForm = (out: Schema): Schema => {
if (
!isStringList(out.type) ||
out.type.length !== 2 ||
!out.type.includes("null")
)
return out;
const { type, description, ...constraints } = out;
const nonNull = (type as readonly string[]).find(
(member) => member !== "null",
)!;
return {
...(description === undefined ? {} : { description }),
anyOf: [{ type: nonNull, ...constraints }, { type: "null" }],
};
};
/** One projection: guidance sentences accumulate while the schema is built. */
class DialectProjection {
readonly notes: string[] = [];
note(sentence: string): void {
if (!this.notes.includes(sentence)) this.notes.push(sentence);
}
project(value: unknown, path: string): unknown {
if (!isRecord(value)) return value;
const source = mergeAllOf(value);
const out: Schema = {};
if (typeof source.type === "string" || isStringList(source.type))
out.type = source.type;
if (typeof source.description === "string")
out.description = truncatedDescription(source.description);
this.objectKeywords(source, out, path);
this.arrayKeywords(source, out, path);
scalarBounds(source, out);
literalKeywords(source, out);
if (isRecord(source.not) && isStringList(source.not.enum))
this.note(
`${label(path)} must not be ${source.not.enum.map((item) => JSON.stringify(item)).join(" or ")}.`,
);
this.unionKeywords(source, out, path);
return nullableForm(out);
}
/** Name and count constraints are dropped; an object's own cross-field
* rules precede those of its properties. */
private objectKeywords(source: Schema, out: Schema, path: string): void {
for (const sentence of dependencyGuidance(source))
this.note(path === "" ? sentence : `In ${label(path)}: ${sentence}`);
if (isRecord(source.properties)) {
// `fromEntries` defines each name as an own property, so a property
// named `__proto__` stays a property rather than setting the prototype.
const properties: Schema = Object.fromEntries(
Object.entries(source.properties)
// A never-valid property is omitted; closed objects still refuse it.
.filter(([, child]) => child !== false)
.map(([name, child]) => [
name,
this.project(child, path === "" ? name : `${path}.${name}`),
]),
);
out.properties = properties;
if (isStringList(source.required)) {
const required = source.required.filter((name) =>
Object.hasOwn(properties, name),
);
if (required.length > 0) out.required = required;
}
}
if (
source.additionalProperties === false &&
(!isRecord(source.patternProperties) ||
Object.keys(source.patternProperties).length === 0)
)
out.additionalProperties = false;
}
/** A tuple advertises the union of its positions. */
private arrayKeywords(source: Schema, out: Schema, path: string): void {
const tuple = Array.isArray(source.prefixItems)
? source.prefixItems
: Array.isArray(source.items)
? source.items
: undefined;
if (tuple !== undefined) {
// Elements past the positions follow `items` (2020-12) or
// `additionalItems` (draft-07), and are unconstrained without either
// unless `maxItems` admits none.
const restSchema = Array.isArray(source.prefixItems)
? source.items
: source.additionalItems;
const bounded =
typeof source.maxItems === "number" && source.maxItems <= tuple.length;
const rest =
restSchema === false || bounded
? []
: [restSchema === undefined ? true : restSchema];
out.items = this.elementUnion([...tuple, ...rest], `${path}[]`);
} else if (isRecord(source.items))
out.items = this.project(source.items, `${path}[]`);
if (source.uniqueItems === true)
this.note(`${label(path)} entries must be distinct.`);
}
/** One element schema accepting every member; any-value members stay open. */
private elementUnion(members: readonly unknown[], path: string): unknown {
return members.some(
(member) =>
member === true ||
(isRecord(member) && Object.keys(member).length === 0),
)
? {}
: this.project({ anyOf: members.filter(isRecord) }, path);
}
/** `oneOf` widens to `anyOf`; string-literal unions merge into one enum. */
private unionKeywords(source: Schema, out: Schema, path: string): void {
const alternatives = Array.isArray(source.anyOf)
? source.anyOf
: Array.isArray(source.oneOf)
? source.oneOf
: undefined;
if (alternatives === undefined) return;
const branches = this.unionBranches(alternatives, path, out.type);
if (
branches.length > 0 &&
out.enum === undefined &&
(out.type === undefined || out.type === "string") &&
branches.every(isStringEnum)
) {
out.type = "string";
out.enum = [
...new Set(branches.flatMap((branch) => (branch as Schema).enum)),
];
return;
}
if (branches.length === 1 && isRecord(branches[0])) {
const branch = branches[0];
// As with `allOf`, a closure is scoped to its own properties: once the
// parent's properties win, neither closure may reject the branch's.
const scoped =
Object.hasOwn(out, "properties") && Object.hasOwn(branch, "properties");
for (const [key, keyword] of Object.entries(branch))
if (!Object.hasOwn(out, key)) out[key] = keyword;
if (scoped) delete out.additionalProperties;
return;
}
if (branches.length < 2) return;
out.anyOf = branches;
const types = new Set(branches.map(branchType));
if (out.type === undefined && types.size === 1 && !types.has(undefined))
out.type = [...types][0];
// Clients require `items` on every array. The union of the branch
// element schemas restates what the branches already enforce.
if (
out.type === "array" &&
out.items === undefined &&
branches.every((branch) => isRecord(branch) && isRecord(branch.items))
)
out.items = this.elementUnion(
branches.map((branch) => (branch as Schema).items),
`${path}[]`,
);
}
/** Flattened, typed from their parent and deduplicated. */
private unionBranches(
branches: readonly unknown[],
path: string,
parentType: unknown,
): unknown[] {
const branchNotes: string[][] = [];
const projectedBranches = distinct(
branches.flatMap((branch) => {
const typed =
typeof parentType === "string" &&
isRecord(branch) &&
branch.type === undefined &&
branch.anyOf === undefined &&
branch.oneOf === undefined
? { ...branch, type: parentType }
: branch;
const projection = new DialectProjection();
const projected = projection.project(typed, path);
branchNotes.push(projection.notes);
return isRecord(projected) &&
Array.isArray(projected.anyOf) &&
onlyKeys(projected, ["anyOf"])
? projected.anyOf
: [projected];
}),
);
for (const note of branchNotes[0] ?? [])
if (branchNotes.every((notes) => notes.includes(note))) this.note(note);
return projectedBranches;
}
}
/** Project one root input schema into the portable advertised dialect. */
export const projectToAdvertisedDialect = (
root: Readonly<Record<string, unknown>>,
): AdvertisedDialectProjection => {
const projection = new DialectProjection();
// The root description joins the tool description whole, not truncated.
const { description, ...rest } = root;
const projected = projection.project(rest, "");
return {
schema: { type: "object", ...(isRecord(projected) ? projected : {}) },
guidance: [
...(typeof description === "string" && description !== ""
? [description]
: []),
...projection.notes,
],
};
};