mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 11:43:20 +00:00
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
This commit is contained in:
1 parent
3d22f0041a
commit
b0e0d52a9f
15 files changed
+726
-810
No files matched your search
@@ -35,7 +35,8 @@ export type AdvertisedDialectRule =
|
||||
| "tool-name"
|
||||
// Claude Code truncates a tool description at 4,096 characters.
|
||||
| "tool-description-length"
|
||||
// Moonshot rejects a parameters schema above its literal size cap (#1484).
|
||||
// Moonshot rejects a parameters schema above its literal size cap (#1484),
|
||||
// measured after clients such as Kimi expand its references.
|
||||
| "input-bytes"
|
||||
// OpenCode and Muse Spark reject nesting deeper than ten levels (#2813, #919).
|
||||
| "input-depth"
|
||||
|
||||
@@ -135,8 +135,21 @@ describe("portable advertised dialect projection", () => {
|
||||
],
|
||||
[
|
||||
"pattern-only allOf members",
|
||||
{ type: "string", allOf: [{ pattern: "^a" }, { pattern: "b$" }] },
|
||||
{ type: "string", pattern: "^a" },
|
||||
{
|
||||
type: "string",
|
||||
allOf: [{ pattern: "^a[a-z]*$" }, { pattern: "^[a-z]*b$" }],
|
||||
},
|
||||
{ type: "string", pattern: "^a[a-z]*$" },
|
||||
],
|
||||
[
|
||||
"pattern in its portable form",
|
||||
{ type: "string", pattern: "^\\d+$" },
|
||||
{ type: "string", pattern: "^[0-9]+$" },
|
||||
],
|
||||
[
|
||||
"pattern without a portable form",
|
||||
{ type: "string", pattern: "^😀$" },
|
||||
{ type: "string" },
|
||||
],
|
||||
[
|
||||
"string literal union",
|
||||
|
||||
@@ -5,6 +5,7 @@ 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
|
||||
@@ -175,7 +176,10 @@ const scalarBounds = (source: Schema, out: Schema): void => {
|
||||
(source[bound] as number) < ADVERTISED_BOUND_LIMIT
|
||||
)
|
||||
out[bound] = source[bound];
|
||||
if (typeof source.pattern === "string") out.pattern = source.pattern;
|
||||
if (typeof source.pattern === "string") {
|
||||
const projected = projectPortablePattern(source.pattern);
|
||||
if (projected.kind !== "unexpressible") out.pattern = projected.pattern;
|
||||
}
|
||||
inclusiveBounds(source, out);
|
||||
};
|
||||
|
||||
|
||||
@@ -5,6 +5,8 @@ import { z } from "zod";
|
||||
|
||||
import { canonicalBase64Schema } from "../domain/stringPatterns.js";
|
||||
import { digestCanonicalValue } from "../domain/canonicalDigest.js";
|
||||
import { ADVERTISED_INPUT_SCHEMA_MAX_BYTES } from "./advertisedDialect.js";
|
||||
import { advertiseToolInput } from "./advertisedTool.js";
|
||||
import { toolContract } from "./toolContracts.js";
|
||||
import {
|
||||
toolInputSchemaWithMetadata,
|
||||
@@ -34,6 +36,37 @@ it.each(["draft-2020-12", "draft-07"] as const)(
|
||||
expect($id).toBe(
|
||||
`urn:rea:tool-output:sha256:${digestCanonicalValue({ target, schema: withoutId }, "Tool output schema")}`,
|
||||
);
|
||||
// The registered input keeps the canonical patterns; the client receives
|
||||
// the dialect projection of it. The output presentation re-emits its own.
|
||||
const advertisedInput = advertiseToolInput(
|
||||
undefined,
|
||||
projectedInput as Record<string, unknown>,
|
||||
{ budgetBytes: ADVERTISED_INPUT_SCHEMA_MAX_BYTES },
|
||||
).inputSchema;
|
||||
const Validator = target === "draft-2020-12" ? Ajv2020 : Ajv;
|
||||
const compile = (schema: unknown) =>
|
||||
new Validator({ strict: false }).compile(schema as object);
|
||||
for (const [schema, exact] of [
|
||||
[projectedInput, true],
|
||||
[advertisedInput, false],
|
||||
[projectedOutput, false],
|
||||
] as const) {
|
||||
const validate = compile(schema);
|
||||
// Neither advertisement keeps the negated pad-bit probe, so each admits
|
||||
// `AB==` while the registered schema and the server still refuse it.
|
||||
for (const [encoded, valid] of [
|
||||
["AA==", true],
|
||||
["AB==", false],
|
||||
["AAAAAA==", false],
|
||||
] as const) {
|
||||
const value = { encoded, literal };
|
||||
expect(validate(value), encoded).toBe(
|
||||
valid || (!exact && encoded === "AB=="),
|
||||
);
|
||||
expect(input.safeParse(value).success, encoded).toBe(valid);
|
||||
expect(output.safeParse(value).success, encoded).toBe(valid);
|
||||
}
|
||||
}
|
||||
for (const projected of [projectedInput, projectedOutput]) {
|
||||
const properties = projected.properties as Record<string, unknown>;
|
||||
const literalProperty = properties.literal as Record<string, unknown>;
|
||||
@@ -51,20 +84,6 @@ it.each(["draft-2020-12", "draft-07"] as const)(
|
||||
default: literal,
|
||||
examples: [literal],
|
||||
});
|
||||
const Validator = target === "draft-2020-12" ? Ajv2020 : Ajv;
|
||||
const validate = new Validator({ strict: false }).compile(projected);
|
||||
// The unbounded pad-bit probe has no stack-safe portable form, so the
|
||||
// advertisement admits `AB==` while the server still refuses it.
|
||||
for (const [encoded, valid, advertised] of [
|
||||
["AA==", true, true],
|
||||
["AB==", false, true],
|
||||
["AAAAAA==", false, false],
|
||||
] as const) {
|
||||
const value = { encoded, literal };
|
||||
expect(validate(value), encoded).toBe(advertised);
|
||||
expect(input.safeParse(value).success, encoded).toBe(valid);
|
||||
expect(output.safeParse(value).success, encoded).toBe(valid);
|
||||
}
|
||||
}
|
||||
},
|
||||
);
|
||||
@@ -227,9 +227,13 @@ describe("compact advertised input schema", () => {
|
||||
});
|
||||
|
||||
it("keeps pattern-admitted property names open in reduced schemas", () => {
|
||||
// Nesting past the dialect's depth limit forces the reduced form.
|
||||
let deep: Record<string, unknown> = { type: "string" };
|
||||
for (let level = 0; level < 12; level++)
|
||||
deep = { type: "object", properties: { next: deep } };
|
||||
const canonical = {
|
||||
type: "object",
|
||||
properties: { a: { type: "string", pattern: "x" } },
|
||||
properties: { a: deep },
|
||||
patternProperties: { "^b$": { type: "string" } },
|
||||
additionalProperties: false,
|
||||
};
|
||||
|
||||
@@ -10,10 +10,10 @@ import {
|
||||
stripAnnotations,
|
||||
} from "./compactJsonSchema.js";
|
||||
|
||||
// The compact input presentation: every advertised input schema is self-contained
|
||||
// (clients such as Kimi expand references before sending tools to Moonshot),
|
||||
// inside the per-tool byte budget, and in the portable advertised dialect.
|
||||
// Canonical server-side validation remains unchanged.
|
||||
// The compact input presentation: every advertised input schema is
|
||||
// self-contained (the dialect admits no `$ref` or `$defs`), inside the
|
||||
// per-tool byte budget, and in the portable advertised dialect. Canonical
|
||||
// server-side validation remains unchanged.
|
||||
|
||||
export type AdvertisedInputSchemaPresentation = "inline" | "reduced";
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ import { expect, it } from "vitest";
|
||||
import { z } from "zod";
|
||||
|
||||
import { BROWSER_TOOL_CONTRACTS } from "./browserToolContracts.js";
|
||||
import { presentInputJsonSchema } from "./inputSchemaPresentation.js";
|
||||
import { presentOutputJsonSchema } from "./outputSchemaPresentation.js";
|
||||
import {
|
||||
advertisedInputJsonSchema,
|
||||
COMPLETE_OBSERVATION_GUIDANCE,
|
||||
@@ -83,39 +83,39 @@ const referenceWideningCases: readonly {
|
||||
{
|
||||
name: "oneOf",
|
||||
schema: {
|
||||
definitions: { off: { const: false } },
|
||||
definitions: { off: { type: "string", pattern: "^😀$" } },
|
||||
properties: { value: { oneOf: [{ $ref: "#/definitions/off" }, {}] } },
|
||||
},
|
||||
input: { value: true },
|
||||
input: { value: "x" },
|
||||
},
|
||||
{
|
||||
name: "not",
|
||||
schema: {
|
||||
definitions: { off: { const: false } },
|
||||
definitions: { off: { type: "string", pattern: "^😀$" } },
|
||||
properties: { value: { not: { $ref: "#/definitions/off" } } },
|
||||
},
|
||||
input: { value: true },
|
||||
input: { value: "x" },
|
||||
},
|
||||
{
|
||||
name: "if",
|
||||
schema: {
|
||||
definitions: { off: { const: false } },
|
||||
definitions: { off: { type: "string", pattern: "^😀$" } },
|
||||
properties: {
|
||||
value: { if: { $ref: "#/definitions/off" }, then: false, else: true },
|
||||
},
|
||||
},
|
||||
input: { value: true },
|
||||
input: { value: "x" },
|
||||
},
|
||||
{
|
||||
name: "chain",
|
||||
schema: {
|
||||
definitions: {
|
||||
off: { const: false },
|
||||
off: { type: "string", pattern: "^😀$" },
|
||||
alias: { $ref: "#/definitions/off" },
|
||||
},
|
||||
properties: { value: { not: { $ref: "#/definitions/alias" } } },
|
||||
},
|
||||
input: { value: true },
|
||||
input: { value: "x" },
|
||||
},
|
||||
{
|
||||
name: "recursive affected",
|
||||
@@ -124,7 +124,7 @@ const referenceWideningCases: readonly {
|
||||
node: {
|
||||
type: "object",
|
||||
properties: {
|
||||
flag: { const: false },
|
||||
flag: { type: "string", pattern: "^😀$" },
|
||||
next: { $ref: "#/definitions/node" },
|
||||
},
|
||||
required: ["flag"],
|
||||
@@ -132,7 +132,7 @@ const referenceWideningCases: readonly {
|
||||
},
|
||||
properties: { value: { not: { $ref: "#/definitions/node" } } },
|
||||
},
|
||||
input: { value: { flag: true } },
|
||||
input: { value: { flag: "x" } },
|
||||
},
|
||||
{
|
||||
name: "literal target unchanged",
|
||||
@@ -147,7 +147,7 @@ const referenceWideningCases: readonly {
|
||||
name: "nested resource unaffected",
|
||||
schema: {
|
||||
$id: "https://example.test/root",
|
||||
definitions: { flag: { const: false } },
|
||||
definitions: { flag: { type: "string", pattern: "^😀$" } },
|
||||
properties: {
|
||||
value: {
|
||||
$id: "child",
|
||||
@@ -197,7 +197,7 @@ it.each(
|
||||
type: "object",
|
||||
...schema,
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = presentOutputJsonSchema(canonical);
|
||||
const create = () =>
|
||||
dialect === "draft-07"
|
||||
? new Ajv({ strict: false })
|
||||
@@ -209,15 +209,17 @@ it.each(
|
||||
expect(advertised.default, `${name} literal data`).toEqual(
|
||||
canonical.default,
|
||||
);
|
||||
// An affected site is rewritten; an unaffected one is left as it was.
|
||||
if (unchanged)
|
||||
expect(advertised.properties, name).toEqual(canonical.properties);
|
||||
else expect(advertised.properties, name).not.toEqual(canonical.properties);
|
||||
},
|
||||
);
|
||||
|
||||
it("keeps an upper contains bound from rejecting canonical items after referenced literal widening", () => {
|
||||
it("keeps an upper contains bound from rejecting canonical items after referenced pattern widening", () => {
|
||||
const canonical = {
|
||||
type: "object",
|
||||
definitions: { off: { const: false } },
|
||||
definitions: { off: { type: "string", pattern: "^😀$" } },
|
||||
properties: {
|
||||
values: {
|
||||
type: "array",
|
||||
@@ -227,17 +229,18 @@ it("keeps an upper contains bound from rejecting canonical items after reference
|
||||
},
|
||||
},
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const input = { values: [false, true] };
|
||||
const advertised = presentOutputJsonSchema(canonical);
|
||||
const input = { values: ["x", "y"] };
|
||||
expect(new Ajv2020({ strict: false }).compile(canonical)(input)).toBe(true);
|
||||
expect(new Ajv2020({ strict: false }).compile(advertised)(input)).toBe(true);
|
||||
expect(advertised).not.toHaveProperty("properties.values.maxContains");
|
||||
});
|
||||
|
||||
it.each([false, true])(
|
||||
"preserves conditional evaluation annotations (referenced: %s)",
|
||||
(referenced) => {
|
||||
const conditional = {
|
||||
if: { properties: { flag: { const: false } } },
|
||||
if: { properties: { flag: { type: "string", pattern: "^😀$" } } },
|
||||
then: { properties: { extra: { type: "string" } } },
|
||||
};
|
||||
const canonical = {
|
||||
@@ -246,12 +249,14 @@ it.each([false, true])(
|
||||
...(referenced ? { $ref: "#/definitions/conditional" } : conditional),
|
||||
unevaluatedProperties: false,
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const input = { flag: false, extra: "kept" };
|
||||
const advertised = presentOutputJsonSchema(canonical);
|
||||
const input = { flag: "😀", extra: "kept" };
|
||||
expect(new Ajv2020({ strict: false }).compile(canonical)(input)).toBe(true);
|
||||
expect(new Ajv2020({ strict: false }).compile(advertised)(input)).toBe(
|
||||
true,
|
||||
);
|
||||
// The widened condition goes, and with it the evaluation it provided.
|
||||
expect(advertised).not.toHaveProperty("unevaluatedProperties");
|
||||
},
|
||||
);
|
||||
|
||||
@@ -261,18 +266,19 @@ it("retains item annotations when only the unsafe contains maximum leaves", () =
|
||||
properties: {
|
||||
values: {
|
||||
type: "array",
|
||||
contains: { const: false },
|
||||
// No portable regex form exists, so the advertisement omits it.
|
||||
contains: { type: "string", pattern: "^😀$" },
|
||||
maxContains: 1,
|
||||
unevaluatedItems: false,
|
||||
},
|
||||
},
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const input = { values: [false] };
|
||||
const advertised = presentOutputJsonSchema(canonical);
|
||||
const input = { values: ["😀"] };
|
||||
expect(new Ajv2020({ strict: false }).compile(canonical)(input)).toBe(true);
|
||||
expect(new Ajv2020({ strict: false }).compile(advertised)(input)).toBe(true);
|
||||
expect(advertised).toHaveProperty("properties.values.contains", {
|
||||
type: "boolean",
|
||||
type: "string",
|
||||
});
|
||||
expect(advertised).toHaveProperty(
|
||||
"properties.values.unevaluatedItems",
|
||||
@@ -285,18 +291,19 @@ it("keeps unaffected root property annotations strict when a child conditional w
|
||||
type: "object",
|
||||
properties: {
|
||||
child: {
|
||||
if: { const: false },
|
||||
if: { type: "string", pattern: "^😀$" },
|
||||
then: { type: "string" },
|
||||
else: { type: "boolean" },
|
||||
},
|
||||
},
|
||||
unevaluatedProperties: false,
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = presentOutputJsonSchema(canonical);
|
||||
const validate = new Ajv2020({ strict: false }).compile(advertised);
|
||||
expect(validate({ child: true })).toBe(true);
|
||||
expect(validate({ child: true, unknown: "reject" })).toBe(false);
|
||||
expect(advertised.unevaluatedProperties).toBe(false);
|
||||
expect(advertised).not.toHaveProperty("properties.child.if");
|
||||
});
|
||||
|
||||
it.each(["draft-07", "draft-2020-12"] as const)(
|
||||
@@ -310,11 +317,11 @@ it.each(["draft-07", "draft-2020-12"] as const)(
|
||||
type: "object",
|
||||
definitions: {
|
||||
number: { type: "number" },
|
||||
alias: { $ref: "#/definitions/number", const: false },
|
||||
alias: { $ref: "#/definitions/number", pattern: "^😀$" },
|
||||
},
|
||||
properties: { value: { not: { $ref: "#/definitions/alias" } } },
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = presentOutputJsonSchema(canonical);
|
||||
const create = () =>
|
||||
dialect === "draft-07"
|
||||
? new Ajv({ strict: false, ignoreKeywordsWithRef: true })
|
||||
@@ -345,7 +352,8 @@ it.each(["draft-07", "draft-2020-12"] as const)(
|
||||
? "http://json-schema.org/draft-07/schema#"
|
||||
: "https://json-schema.org/draft/2020-12/schema",
|
||||
type: "object",
|
||||
definitions: { off: { const: false } },
|
||||
// No portable regex form exists, so the advertisement omits it.
|
||||
definitions: { off: { type: "string", pattern: "^😀$" } },
|
||||
default: literal,
|
||||
properties: {
|
||||
value: { $ref: "#/default/conditional" },
|
||||
@@ -353,7 +361,7 @@ it.each(["draft-07", "draft-2020-12"] as const)(
|
||||
},
|
||||
unevaluatedProperties: false,
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = presentOutputJsonSchema(canonical);
|
||||
const create = () =>
|
||||
dialect === "draft-07"
|
||||
? new Ajv({ strict: false })
|
||||
@@ -381,11 +389,14 @@ it("does not treat unused definitions as validation dependencies", () => {
|
||||
type: "object",
|
||||
properties: {
|
||||
value: {
|
||||
not: { type: "number", definitions: { unused: { const: false } } },
|
||||
not: {
|
||||
type: "number",
|
||||
definitions: { unused: { type: "string", pattern: "^😀$" } },
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = presentOutputJsonSchema(canonical);
|
||||
expect(advertised).toHaveProperty("properties.value.not.type", "number");
|
||||
const validate = new Ajv2020({ strict: false }).compile(advertised);
|
||||
expect(validate({ value: "kept" })).toBe(true);
|
||||
|
||||
@@ -4,16 +4,12 @@ import {
|
||||
} from "./jsonSchemaReferences.js";
|
||||
import { isDeepStrictEqual } from "node:util";
|
||||
|
||||
import { advertisedSchemaPatterns } from "./advertisedDialect.js";
|
||||
import { dependencyGuidance } from "./advertisedDialectProjection.js";
|
||||
import { projectPortablePattern } from "./portablePattern.js";
|
||||
import type { SchemaAnnotations } from "../domain/schemaAnnotations.js";
|
||||
import {
|
||||
schemaArrays,
|
||||
schemaChildren,
|
||||
schemaMaps,
|
||||
schemaPointerSteps,
|
||||
schemaSubschemas,
|
||||
} from "./jsonSchemaKeywords.js";
|
||||
|
||||
const isObject = (value: unknown): value is Readonly<Record<string, unknown>> =>
|
||||
@@ -154,41 +150,6 @@ const inputGroup = (branch: Readonly<Record<string, unknown>>): string => {
|
||||
return [...required, ...optional].join(" + ");
|
||||
};
|
||||
|
||||
type SchemaNormalization = {
|
||||
readonly schema: unknown;
|
||||
readonly changed: boolean;
|
||||
};
|
||||
|
||||
// A branch that also references another schema is not judged by its own
|
||||
// keywords: draft-07 ignores a reference's siblings, and the target may admit
|
||||
// more than a boolean. Such unions keep the `anyOf` fallback.
|
||||
const hasReference = (schema: Readonly<Record<string, unknown>>): boolean =>
|
||||
["$ref", "$dynamicRef", "$recursiveRef"].some(
|
||||
(keyword) => typeof schema[keyword] === "string",
|
||||
);
|
||||
|
||||
const isBooleanLiteralSchema = (schema: unknown): boolean =>
|
||||
isObject(schema) &&
|
||||
!hasReference(schema) &&
|
||||
(typeof schema.const === "boolean" ||
|
||||
(Array.isArray(schema.enum) &&
|
||||
schema.enum.length > 0 &&
|
||||
schema.enum.every((value) => typeof value === "boolean")));
|
||||
|
||||
const isBooleanSchema = (schema: unknown): boolean =>
|
||||
isObject(schema) &&
|
||||
((schema.type === "boolean" && !hasReference(schema)) ||
|
||||
isBooleanLiteralSchema(schema));
|
||||
|
||||
/**
|
||||
* Whether a union collapses to `type: "boolean"` once a branch changes. The
|
||||
* decision reads the canonical branches, so a branch that becomes boolean only
|
||||
* because presentation relaxed its reference keeps the union, and pointers into
|
||||
* the union stay resolvable (see `throughRemovableLocation`).
|
||||
*/
|
||||
const collapsesToBoolean = (branches: readonly unknown[]): boolean =>
|
||||
branches.length > 0 && branches.every(isBooleanSchema);
|
||||
|
||||
const isObjectKeyword = (key: string) => schemaMaps.has(key);
|
||||
const isArrayKeyword = (key: string) => schemaArrays.has(key);
|
||||
const isChildKeyword = (key: string) => schemaChildren.has(key);
|
||||
@@ -263,506 +224,10 @@ const referencedDefaultPaths = (
|
||||
return kept;
|
||||
};
|
||||
|
||||
const preserveSharedDefault = (
|
||||
schema: Record<string, unknown>,
|
||||
branches: readonly unknown[],
|
||||
): void => {
|
||||
if (schema.default !== undefined) return;
|
||||
const defaults = branches
|
||||
.filter(isObject)
|
||||
.map((branch) => branch.default)
|
||||
.filter((value) => value !== undefined);
|
||||
if (
|
||||
defaults.length > 0 &&
|
||||
defaults.every((value) => isDeepStrictEqual(value, defaults[0]))
|
||||
)
|
||||
schema.default = defaults[0];
|
||||
};
|
||||
|
||||
const hasNormalizedLiteral = (schema: Readonly<Record<string, unknown>>) =>
|
||||
typeof schema.const === "boolean" ||
|
||||
schema.const === "" ||
|
||||
(Array.isArray(schema.enum) &&
|
||||
((schema.enum.length > 0 &&
|
||||
schema.enum.every((item) => typeof item === "boolean")) ||
|
||||
schema.enum.includes("")));
|
||||
|
||||
/**
|
||||
* A pattern the portable projection cannot reproduce exactly widens its site.
|
||||
* Exact re-emission keeps the site's meaning, so its dependents stay intact.
|
||||
*/
|
||||
const hasWidenedPattern = (schema: Readonly<Record<string, unknown>>) =>
|
||||
typeof schema.pattern === "string" &&
|
||||
projectPortablePattern(schema.pattern).kind !== "exact";
|
||||
|
||||
interface NormalizationOptions {
|
||||
/** Rewrite boolean and empty-string literals some gateways refuse. */
|
||||
readonly literals: boolean;
|
||||
}
|
||||
const INPUT_NORMALIZATION: NormalizationOptions = { literals: true };
|
||||
const OUTPUT_NORMALIZATION: NormalizationOptions = { literals: false };
|
||||
|
||||
/** One projection owns actual rewrite sites and their scoped validation dependencies. */
|
||||
/**
|
||||
* Keywords normalization may remove or rename: a widened `not` or `if` is
|
||||
* dropped with its branches, a widened `oneOf` becomes `anyOf`, and lost
|
||||
* evaluation drops `unevaluatedProperties` and `unevaluatedItems`.
|
||||
*/
|
||||
const REMOVABLE_KEYWORDS = new Set([
|
||||
"oneOf",
|
||||
"not",
|
||||
"if",
|
||||
"then",
|
||||
"else",
|
||||
"unevaluatedProperties",
|
||||
"unevaluatedItems",
|
||||
]);
|
||||
|
||||
/**
|
||||
* Whether a pointer from `root` passes through a keyword normalization may
|
||||
* remove. An `anyOf` is removed only when it collapses: every branch boolean.
|
||||
*/
|
||||
/** Keywords a relaxed draft-07 reference keeps; its other siblings go. */
|
||||
const DRAFT07_REDUCED_REFERENCE_KEYS = new Set([
|
||||
"$id",
|
||||
"$schema",
|
||||
"$anchor",
|
||||
"$defs",
|
||||
"definitions",
|
||||
"description",
|
||||
"title",
|
||||
"default",
|
||||
"examples",
|
||||
"$comment",
|
||||
]);
|
||||
|
||||
const throughRemovableLocation = (
|
||||
root: unknown,
|
||||
path: readonly string[],
|
||||
draft07: boolean,
|
||||
): boolean => {
|
||||
let value = root;
|
||||
for (const [index, step] of schemaPointerSteps(path).entries()) {
|
||||
// Relaxing a draft-07 reference removes its ignored siblings, including
|
||||
// literal-valued ones such as `const`.
|
||||
if (
|
||||
draft07 &&
|
||||
step.kind !== "entry" &&
|
||||
isObject(value) &&
|
||||
hasReference(value) &&
|
||||
!DRAFT07_REDUCED_REFERENCE_KEYS.has(step.keyword)
|
||||
)
|
||||
return true;
|
||||
if (
|
||||
step.kind === "keyword" &&
|
||||
(REMOVABLE_KEYWORDS.has(step.keyword) ||
|
||||
(step.keyword === "anyOf" &&
|
||||
isObject(value) &&
|
||||
Array.isArray(value.anyOf) &&
|
||||
collapsesToBoolean(value.anyOf)))
|
||||
)
|
||||
return true;
|
||||
value =
|
||||
typeof value === "object" && value !== null
|
||||
? Reflect.get(value, path[index]!)
|
||||
: undefined;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
|
||||
const normalizationContext = (
|
||||
root: Readonly<Record<string, unknown>>,
|
||||
options: NormalizationOptions,
|
||||
) => {
|
||||
const references = new JsonSchemaReferences(root);
|
||||
type Fact = {
|
||||
changed: boolean;
|
||||
lostEvaluation: boolean;
|
||||
dependents: Set<Fact>;
|
||||
evaluationDependents: Set<Fact>;
|
||||
opaqueReference?: Fact;
|
||||
};
|
||||
const sites = new Map<JsonSchemaScope | undefined, WeakSet<object>>();
|
||||
const pending: { schema: unknown; scope: JsonSchemaScope | undefined }[] = [
|
||||
{ schema: root, scope: references.rootScope },
|
||||
];
|
||||
const entries: {
|
||||
schema: Readonly<Record<string, unknown>>;
|
||||
scope: JsonSchemaScope | undefined;
|
||||
}[] = [];
|
||||
// Literal payloads are not rewritten, even when a reference evaluates them.
|
||||
while (pending.length > 0) {
|
||||
const entry = pending.pop()!;
|
||||
if (!isObject(entry.schema)) continue;
|
||||
const scope = references.enter(entry.schema, entry.scope);
|
||||
let seen = sites.get(scope);
|
||||
if (seen === undefined) sites.set(scope, (seen = new WeakSet()));
|
||||
if (seen.has(entry.schema)) continue;
|
||||
seen.add(entry.schema);
|
||||
entries.push({ schema: entry.schema, scope });
|
||||
for (const schema of schemaSubschemas(entry.schema, {
|
||||
includeDefinitions: true,
|
||||
}))
|
||||
pending.push({ schema, scope });
|
||||
}
|
||||
const indexed = new Map<JsonSchemaScope | undefined, WeakMap<object, Fact>>();
|
||||
const work: {
|
||||
schema: Readonly<Record<string, unknown>>;
|
||||
scope: JsonSchemaScope | undefined;
|
||||
fact: Fact;
|
||||
}[] = [];
|
||||
const changed: Fact[] = [];
|
||||
const untracked: Fact[] = [];
|
||||
const factAt = (
|
||||
schema: unknown,
|
||||
inherited: JsonSchemaScope | undefined,
|
||||
): Fact | undefined => {
|
||||
if (!isObject(schema)) return undefined;
|
||||
const scope = references.enter(schema, inherited);
|
||||
let facts = indexed.get(scope);
|
||||
if (facts === undefined) indexed.set(scope, (facts = new WeakMap()));
|
||||
const existing = facts.get(schema);
|
||||
if (existing !== undefined) return existing;
|
||||
const fact: Fact = {
|
||||
changed: false,
|
||||
lostEvaluation: false,
|
||||
dependents: new Set(),
|
||||
evaluationDependents: new Set(),
|
||||
};
|
||||
facts.set(schema, fact);
|
||||
work.push({ schema, scope, fact });
|
||||
return fact;
|
||||
};
|
||||
for (const { schema, scope } of entries) factAt(schema, scope);
|
||||
for (let index = 0; index < work.length; index++) {
|
||||
const { schema, scope, fact } = work[index]!;
|
||||
const ignoresSiblings =
|
||||
scope?.dialect === "draft-07" && typeof schema.$ref === "string";
|
||||
const projection =
|
||||
typeof schema.pattern === "string"
|
||||
? projectPortablePattern(schema.pattern)
|
||||
: undefined;
|
||||
const opaquePatternChanged =
|
||||
!sites.get(scope)?.has(schema) &&
|
||||
projection !== undefined &&
|
||||
(projection.kind !== "exact" || projection.pattern !== schema.pattern);
|
||||
if (
|
||||
!ignoresSiblings &&
|
||||
(opaquePatternChanged ||
|
||||
(sites.get(scope)?.has(schema) &&
|
||||
((options.literals && hasNormalizedLiteral(schema)) ||
|
||||
hasWidenedPattern(schema))))
|
||||
) {
|
||||
fact.changed = true;
|
||||
changed.push(fact);
|
||||
}
|
||||
if (typeof schema.$ref === "string") {
|
||||
const target = references.resolve(scope, schema.$ref);
|
||||
if (
|
||||
target.kind === "target" &&
|
||||
!throughRemovableLocation(
|
||||
scope?.root,
|
||||
target.path,
|
||||
scope?.dialect === "draft-07",
|
||||
)
|
||||
) {
|
||||
const dependency = factAt(target.value, scope);
|
||||
dependency?.dependents.add(fact);
|
||||
dependency?.evaluationDependents.add(fact);
|
||||
if (
|
||||
dependency !== undefined &&
|
||||
isObject(target.value) &&
|
||||
!sites.get(references.enter(target.value, scope))?.has(target.value)
|
||||
)
|
||||
fact.opaqueReference = dependency;
|
||||
} else if (target.kind !== "unresolved") {
|
||||
// Named anchors and pointers into removable locations are not
|
||||
// followed by this owner. Relax them when normalizing so a widened or
|
||||
// moved target cannot make a negation stricter or leave a dangling
|
||||
// reference.
|
||||
fact.opaqueReference = fact;
|
||||
if (!fact.changed) {
|
||||
fact.changed = true;
|
||||
changed.push(fact);
|
||||
}
|
||||
} else untracked.push(fact);
|
||||
}
|
||||
if (
|
||||
scope?.dialect !== "draft-07" &&
|
||||
(typeof schema.$dynamicRef === "string" ||
|
||||
typeof schema.$recursiveRef === "string")
|
||||
)
|
||||
untracked.push(fact);
|
||||
if (!ignoresSiblings)
|
||||
for (const child of schemaSubschemas(schema, {
|
||||
includeDefinitions: false,
|
||||
}))
|
||||
factAt(child, scope)?.dependents.add(fact);
|
||||
if (!ignoresSiblings)
|
||||
for (const key of [
|
||||
"allOf",
|
||||
"anyOf",
|
||||
"oneOf",
|
||||
"if",
|
||||
"then",
|
||||
"else",
|
||||
"dependentSchemas",
|
||||
"dependencies",
|
||||
]) {
|
||||
const value = schema[key];
|
||||
const children = Array.isArray(value)
|
||||
? value
|
||||
: schemaMaps.has(key) && isObject(value)
|
||||
? Object.values(value)
|
||||
: [value];
|
||||
for (const child of children)
|
||||
factAt(child, scope)?.evaluationDependents.add(fact);
|
||||
}
|
||||
}
|
||||
// Dynamic targets depend on the evaluation path, and an unresolved target
|
||||
// may be an embedded resource this owner rewrote. Neither is followed, so
|
||||
// once anything widens, relax them like named anchors.
|
||||
if (changed.length > 0)
|
||||
for (const fact of untracked) {
|
||||
fact.opaqueReference = fact;
|
||||
if (!fact.changed) {
|
||||
fact.changed = true;
|
||||
changed.push(fact);
|
||||
}
|
||||
}
|
||||
for (let index = 0; index < changed.length; index++)
|
||||
for (const dependent of changed[index]!.dependents)
|
||||
if (!dependent.changed) {
|
||||
dependent.changed = true;
|
||||
changed.push(dependent);
|
||||
}
|
||||
const lost: Fact[] = [];
|
||||
for (const { schema, scope, fact } of work)
|
||||
if (
|
||||
sites.get(scope)?.has(schema) &&
|
||||
(fact.opaqueReference?.changed ||
|
||||
(!(scope?.dialect === "draft-07" && typeof schema.$ref === "string") &&
|
||||
factAt(schema.if, scope)?.changed))
|
||||
) {
|
||||
fact.lostEvaluation = true;
|
||||
lost.push(fact);
|
||||
}
|
||||
for (let index = 0; index < lost.length; index++)
|
||||
for (const dependent of lost[index]!.evaluationDependents)
|
||||
if (!dependent.lostEvaluation) {
|
||||
dependent.lostEvaluation = true;
|
||||
lost.push(dependent);
|
||||
}
|
||||
return {
|
||||
references,
|
||||
options,
|
||||
changed: (schema: object, scope: JsonSchemaScope | undefined) =>
|
||||
indexed.get(scope)?.get(schema)?.changed === true,
|
||||
lostEvaluation: (schema: object, scope: JsonSchemaScope | undefined) =>
|
||||
indexed.get(scope)?.get(schema)?.lostEvaluation === true,
|
||||
reduceReference: (schema: object, scope: JsonSchemaScope | undefined) =>
|
||||
indexed.get(scope)?.get(schema)?.opaqueReference?.changed === true,
|
||||
};
|
||||
};
|
||||
|
||||
/** Drop boolean and empty-string literals, keeping the node's type. */
|
||||
const widenGatewayLiterals = (node: Record<string, unknown>): void => {
|
||||
if (typeof node.const === "boolean") {
|
||||
delete node.const;
|
||||
if (node.type === undefined) node.type = "boolean";
|
||||
}
|
||||
if (node.const === "") {
|
||||
delete node.const;
|
||||
if (node.type === undefined) node.type = "string";
|
||||
}
|
||||
if (
|
||||
Array.isArray(node.enum) &&
|
||||
node.enum.length > 0 &&
|
||||
node.enum.every((item) => typeof item === "boolean")
|
||||
) {
|
||||
delete node.enum;
|
||||
if (node.type === undefined) node.type = "boolean";
|
||||
}
|
||||
if (Array.isArray(node.enum) && node.enum.includes("")) {
|
||||
// Removing only the empty member would reject a canonical-valid input.
|
||||
// Gemini transports turn const into enum and refuse empty enum members.
|
||||
const values = node.enum;
|
||||
delete node.enum;
|
||||
if (
|
||||
node.type === undefined &&
|
||||
values.every((item) => typeof item === "string")
|
||||
)
|
||||
node.type = "string";
|
||||
}
|
||||
};
|
||||
|
||||
const normalizeAdvertisedSchema = (
|
||||
value: unknown,
|
||||
options: NormalizationOptions,
|
||||
context?: ReturnType<typeof normalizationContext>,
|
||||
inherited?: JsonSchemaScope,
|
||||
): SchemaNormalization => {
|
||||
if (!isObject(value)) return { schema: value, changed: false };
|
||||
const owner = context ?? normalizationContext(value, options);
|
||||
const scope = owner.references.enter(
|
||||
value,
|
||||
context === undefined ? owner.references.rootScope : inherited,
|
||||
);
|
||||
const normalize = (child: unknown) =>
|
||||
normalizeAdvertisedSchema(child, options, owner, scope);
|
||||
const node: Record<string, unknown> = { ...value };
|
||||
const changed = owner.changed(value, scope);
|
||||
const normalizeMap = (map: Readonly<Record<string, unknown>>) =>
|
||||
Object.fromEntries(
|
||||
Object.entries(map).map(([name, child]) => [
|
||||
name,
|
||||
normalize(child).schema,
|
||||
]),
|
||||
);
|
||||
|
||||
for (const [key, child] of Object.entries(value)) {
|
||||
if (schemaMaps.has(key) && isObject(child)) {
|
||||
node[key] = normalizeMap(child);
|
||||
} else if (
|
||||
schemaArrays.has(key) &&
|
||||
key !== "anyOf" &&
|
||||
key !== "oneOf" &&
|
||||
Array.isArray(child)
|
||||
) {
|
||||
node[key] = child.map(normalize).map((result) => result.schema);
|
||||
} else if (
|
||||
schemaChildren.has(key) &&
|
||||
key !== "not" &&
|
||||
key !== "if" &&
|
||||
key !== "then" &&
|
||||
key !== "else"
|
||||
) {
|
||||
const results = Array.isArray(child)
|
||||
? child.map(normalize)
|
||||
: [normalize(child)];
|
||||
const nestedChanged = results.some((result) => result.changed);
|
||||
if (
|
||||
key === "contains" &&
|
||||
nestedChanged &&
|
||||
value.maxContains !== undefined
|
||||
) {
|
||||
delete node.maxContains;
|
||||
node.contains = results[0]?.schema;
|
||||
} else {
|
||||
node[key] = Array.isArray(child)
|
||||
? results.map((result) => result.schema)
|
||||
: results[0]?.schema;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (typeof node.pattern === "string") {
|
||||
// Clients refuse the complete tools request over one pattern their regex
|
||||
// engine cannot compile. A widened or omitted pattern marks this site
|
||||
// changed, so enclosing `not`, `if` and `oneOf` keep only widening.
|
||||
const projected = projectPortablePattern(node.pattern);
|
||||
if (projected.kind === "unexpressible") delete node.pattern;
|
||||
else node.pattern = projected.pattern;
|
||||
}
|
||||
if (options.literals) widenGatewayLiterals(node);
|
||||
|
||||
const negated = Object.hasOwn(value, "not")
|
||||
? normalize(value.not)
|
||||
: undefined;
|
||||
if (negated?.changed) {
|
||||
// Widening a predicate under `not` narrows the containing schema.
|
||||
delete node.not;
|
||||
} else if (negated !== undefined) {
|
||||
node.not = negated.schema;
|
||||
}
|
||||
|
||||
const conditional = Object.hasOwn(value, "if")
|
||||
? normalize(value.if)
|
||||
: undefined;
|
||||
const thenBranch = Object.hasOwn(value, "then")
|
||||
? normalize(value.then)
|
||||
: undefined;
|
||||
const elseBranch = Object.hasOwn(value, "else")
|
||||
? normalize(value.else)
|
||||
: undefined;
|
||||
if (conditional?.changed) {
|
||||
// Changing the predicate can route canonical-valid inputs into a rejecting branch.
|
||||
delete node.if;
|
||||
delete node.then;
|
||||
delete node.else;
|
||||
} else {
|
||||
if (conditional !== undefined) node.if = conditional.schema;
|
||||
if (thenBranch !== undefined) {
|
||||
node.then = thenBranch.schema;
|
||||
}
|
||||
if (elseBranch !== undefined) {
|
||||
node.else = elseBranch.schema;
|
||||
}
|
||||
}
|
||||
|
||||
for (const combinator of ["anyOf", "oneOf"] as const) {
|
||||
const branches = value[combinator];
|
||||
if (!Array.isArray(branches)) continue;
|
||||
const normalized = branches.map(normalize);
|
||||
const schemas = normalized.map((result) => result.schema);
|
||||
const branchesChanged = normalized.some((result) => result.changed);
|
||||
if (combinator === "oneOf" && branchesChanged) {
|
||||
const booleanLiteralsOnly = branches.every(isBooleanLiteralSchema);
|
||||
if (booleanLiteralsOnly) {
|
||||
node.type = "boolean";
|
||||
preserveSharedDefault(node, schemas);
|
||||
delete node.oneOf;
|
||||
continue;
|
||||
}
|
||||
// `anyOf` retains branch guidance without allowing widened branches to
|
||||
// reject inputs that were accepted by exactly one canonical branch.
|
||||
delete node.oneOf;
|
||||
if (Array.isArray(node.anyOf)) {
|
||||
const existingAllOf = Array.isArray(node.allOf) ? node.allOf : [];
|
||||
node.allOf = [...existingAllOf, { anyOf: schemas }];
|
||||
} else {
|
||||
node.anyOf = schemas;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (branchesChanged && collapsesToBoolean(branches)) {
|
||||
node.type = "boolean";
|
||||
preserveSharedDefault(node, schemas);
|
||||
delete node[combinator];
|
||||
continue;
|
||||
}
|
||||
node[combinator] = schemas;
|
||||
}
|
||||
|
||||
if (owner.lostEvaluation(value, scope)) {
|
||||
delete node.unevaluatedProperties;
|
||||
delete node.unevaluatedItems;
|
||||
}
|
||||
if (owner.reduceReference(value, scope)) {
|
||||
// The target is also caller literal data. Keep that data intact and relax
|
||||
// this affected reference rather than copy or mutate its executable view.
|
||||
if (scope?.dialect === "draft-07") {
|
||||
for (const key of Object.keys(node))
|
||||
if (!DRAFT07_REDUCED_REFERENCE_KEYS.has(key)) delete node[key];
|
||||
} else {
|
||||
delete node.$ref;
|
||||
delete node.$dynamicRef;
|
||||
delete node.$recursiveRef;
|
||||
}
|
||||
node.description = [
|
||||
node.description,
|
||||
"This referenced input schema is advertised in reduced form; the server validates the complete canonical input.",
|
||||
]
|
||||
.filter((text) => typeof text === "string")
|
||||
.join(" ");
|
||||
}
|
||||
return { schema: node, changed };
|
||||
};
|
||||
|
||||
// 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.
|
||||
// The advertised dialect's `root-shape` rule requires a plain object root
|
||||
// without a combinator. 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>,
|
||||
references: JsonSchemaReferences,
|
||||
@@ -980,7 +445,11 @@ const presentDiscriminatedRoot = (
|
||||
};
|
||||
};
|
||||
|
||||
/** Describe canonical input fields and present the root as one object. */
|
||||
/**
|
||||
* Describe canonical input fields and present the root as one object. Every
|
||||
* other portability rule (patterns, literals, dependencies as prose) belongs
|
||||
* to the advertised dialect projection that the listed presentation applies.
|
||||
*/
|
||||
export const presentInputJsonSchema = (
|
||||
root: Record<string, unknown>,
|
||||
describeProperty: (property: string) => string | undefined,
|
||||
@@ -997,109 +466,5 @@ export const presentInputJsonSchema = (
|
||||
references.rootScope,
|
||||
describeProperty,
|
||||
);
|
||||
if (!isObject(described))
|
||||
return normalizeAdvertisedSchema(flattened, INPUT_NORMALIZATION)
|
||||
.schema as Record<string, unknown>;
|
||||
const {
|
||||
dependencies: _dependencies,
|
||||
dependentRequired: _dependentRequired,
|
||||
...presentation
|
||||
} = described;
|
||||
const dependencies = dependencyGuidance(described);
|
||||
if (dependencies.length === 0)
|
||||
return normalizeAdvertisedSchema(presentation, INPUT_NORMALIZATION)
|
||||
.schema as Record<string, unknown>;
|
||||
const description = [
|
||||
typeof presentation.description === "string"
|
||||
? presentation.description
|
||||
: undefined,
|
||||
...dependencies,
|
||||
].filter((text) => text !== undefined);
|
||||
return normalizeAdvertisedSchema(
|
||||
{ ...presentation, description: description.join(" ") },
|
||||
INPUT_NORMALIZATION,
|
||||
).schema as Record<string, unknown>;
|
||||
};
|
||||
|
||||
/**
|
||||
* Present an output schema with portable patterns. SDK clients compile every
|
||||
* listed output schema; literals stay, since no model reads them.
|
||||
*/
|
||||
export const presentOutputJsonSchema = (
|
||||
root: Record<string, unknown>,
|
||||
): Record<string, unknown> => {
|
||||
const patterns = advertisedSchemaPatterns(root).map(({ pattern }) => ({
|
||||
pattern,
|
||||
projection: projectPortablePattern(pattern),
|
||||
}));
|
||||
if (hasLiteralReference(root))
|
||||
return normalizeAdvertisedSchema(root, OUTPUT_NORMALIZATION)
|
||||
.schema as Record<string, unknown>;
|
||||
// Output schemas reach several megabytes. Exact re-emission changes no
|
||||
// dependent, so only a widened pattern needs the dependency analysis.
|
||||
if (patterns.some(({ projection }) => projection.kind !== "exact"))
|
||||
return normalizeAdvertisedSchema(root, OUTPUT_NORMALIZATION)
|
||||
.schema as Record<string, unknown>;
|
||||
if (
|
||||
patterns.every(
|
||||
({ pattern, projection }) =>
|
||||
projection.kind === "exact" && projection.pattern === pattern,
|
||||
)
|
||||
)
|
||||
return root;
|
||||
return replaceExactPatterns(root) as Record<string, unknown>;
|
||||
};
|
||||
|
||||
/** A reference into literal data needs dependency analysis, not in-place rewriting. */
|
||||
const hasLiteralReference = (root: Record<string, unknown>): boolean => {
|
||||
const pending: unknown[] = [root];
|
||||
const visited = new WeakSet<object>();
|
||||
while (pending.length > 0) {
|
||||
const value = pending.pop();
|
||||
if (!isObject(value) || visited.has(value)) continue;
|
||||
visited.add(value);
|
||||
if (typeof value.$ref === "string") {
|
||||
try {
|
||||
const reference = decodeURIComponent(value.$ref);
|
||||
if (
|
||||
/(?:^#\/|\/)(?:default|const|enum|examples)(?:\/|$)/u.test(reference)
|
||||
)
|
||||
return true;
|
||||
} catch {
|
||||
// An invalid fragment cannot name one of these locations.
|
||||
}
|
||||
}
|
||||
pending.push(...schemaSubschemas(value, { includeDefinitions: true }));
|
||||
}
|
||||
return false;
|
||||
};
|
||||
|
||||
/** Copy schema positions, replacing each pattern with its exact portable form. */
|
||||
const replaceExactPatterns = (schema: unknown): unknown => {
|
||||
if (!isObject(schema)) return schema;
|
||||
return Object.fromEntries(
|
||||
Object.entries(schema).map(([key, value]) => {
|
||||
if (key === "pattern" && typeof value === "string") {
|
||||
const projection = projectPortablePattern(value);
|
||||
return [key, projection.kind === "exact" ? projection.pattern : value];
|
||||
}
|
||||
if (schemaMaps.has(key) && isObject(value))
|
||||
return [
|
||||
key,
|
||||
Object.fromEntries(
|
||||
Object.entries(value).map(([name, child]) => [
|
||||
name,
|
||||
replaceExactPatterns(child),
|
||||
]),
|
||||
),
|
||||
];
|
||||
if (
|
||||
(schemaArrays.has(key) || schemaChildren.has(key)) &&
|
||||
Array.isArray(value)
|
||||
)
|
||||
return [key, value.map(replaceExactPatterns)];
|
||||
if (schemaChildren.has(key)) return [key, replaceExactPatterns(value)];
|
||||
return [key, value];
|
||||
}),
|
||||
);
|
||||
return isObject(described) ? { ...described } : flattened;
|
||||
};
|
||||
@@ -0,0 +1,515 @@
|
||||
import {
|
||||
JsonSchemaReferences,
|
||||
type JsonSchemaScope,
|
||||
} from "./jsonSchemaReferences.js";
|
||||
import { isRecord as isObject } from "../domain/isRecord.js";
|
||||
import { advertisedSchemaPatterns } from "./advertisedDialect.js";
|
||||
import { projectPortablePattern } from "./portablePattern.js";
|
||||
import {
|
||||
schemaArrays,
|
||||
schemaChildren,
|
||||
schemaMaps,
|
||||
schemaPointerSteps,
|
||||
schemaSubschemas,
|
||||
} from "./jsonSchemaKeywords.js";
|
||||
|
||||
// Listed output schemas keep the canonical structure; SDK clients compile
|
||||
// them, so every pattern is re-emitted in the portable grammar. A pattern
|
||||
// without an exact portable form widens its site, and enclosing `not`, `if`,
|
||||
// `oneOf` and references that depend on that site keep only widening. Input
|
||||
// schemas take the advertised dialect projection instead, which owns their
|
||||
// patterns.
|
||||
|
||||
type SchemaNormalization = {
|
||||
readonly schema: unknown;
|
||||
readonly changed: boolean;
|
||||
};
|
||||
|
||||
// Draft-07 ignores the siblings of a reference, so relaxing one removes them.
|
||||
const hasReference = (schema: Readonly<Record<string, unknown>>): boolean =>
|
||||
["$ref", "$dynamicRef", "$recursiveRef"].some(
|
||||
(keyword) => typeof schema[keyword] === "string",
|
||||
);
|
||||
|
||||
/**
|
||||
* A pattern the portable projection cannot reproduce exactly widens its site.
|
||||
* Exact re-emission keeps the site's meaning, so its dependents stay intact.
|
||||
*/
|
||||
const hasWidenedPattern = (schema: Readonly<Record<string, unknown>>) =>
|
||||
typeof schema.pattern === "string" &&
|
||||
projectPortablePattern(schema.pattern).kind !== "exact";
|
||||
|
||||
/** One projection owns actual rewrite sites and their scoped validation dependencies. */
|
||||
/**
|
||||
* Keywords normalization may remove or rename: a widened `not` or `if` is
|
||||
* dropped with its branches, a widened `oneOf` becomes `anyOf`, and lost
|
||||
* evaluation drops `unevaluatedProperties` and `unevaluatedItems`.
|
||||
*/
|
||||
const REMOVABLE_KEYWORDS = new Set([
|
||||
"oneOf",
|
||||
"not",
|
||||
"if",
|
||||
"then",
|
||||
"else",
|
||||
"unevaluatedProperties",
|
||||
"unevaluatedItems",
|
||||
]);
|
||||
|
||||
/** Keywords a relaxed draft-07 reference keeps; its other siblings go. */
|
||||
const DRAFT07_REDUCED_REFERENCE_KEYS = new Set([
|
||||
"$id",
|
||||
"$schema",
|
||||
"$anchor",
|
||||
"$defs",
|
||||
"definitions",
|
||||
"description",
|
||||
"title",
|
||||
"default",
|
||||
"examples",
|
||||
"$comment",
|
||||
]);
|
||||
|
||||
const throughRemovableLocation = (
|
||||
root: unknown,
|
||||
path: readonly string[],
|
||||
draft07: boolean,
|
||||
): boolean => {
|
||||
let value = root;
|
||||
for (const [index, step] of schemaPointerSteps(path).entries()) {
|
||||
// Relaxing a draft-07 reference removes its ignored siblings, including
|
||||
// literal-valued ones such as `const`.
|
||||
if (
|
||||
draft07 &&
|
||||
step.kind !== "entry" &&
|
||||
isObject(value) &&
|
||||
hasReference(value) &&
|
||||
!DRAFT07_REDUCED_REFERENCE_KEYS.has(step.keyword)
|
||||
)
|
||||
return true;
|
||||
if (step.kind === "keyword" && REMOVABLE_KEYWORDS.has(step.keyword))
|
||||
return true;
|
||||
value =
|
||||
typeof value === "object" && value !== null
|
||||
? Reflect.get(value, path[index]!)
|
||||
: undefined;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
|
||||
const normalizationContext = (root: Readonly<Record<string, unknown>>) => {
|
||||
const references = new JsonSchemaReferences(root);
|
||||
type Fact = {
|
||||
changed: boolean;
|
||||
lostEvaluation: boolean;
|
||||
dependents: Set<Fact>;
|
||||
evaluationDependents: Set<Fact>;
|
||||
opaqueReference?: Fact;
|
||||
};
|
||||
const sites = new Map<JsonSchemaScope | undefined, WeakSet<object>>();
|
||||
const pending: { schema: unknown; scope: JsonSchemaScope | undefined }[] = [
|
||||
{ schema: root, scope: references.rootScope },
|
||||
];
|
||||
const entries: {
|
||||
schema: Readonly<Record<string, unknown>>;
|
||||
scope: JsonSchemaScope | undefined;
|
||||
}[] = [];
|
||||
// Literal payloads are not rewritten, even when a reference evaluates them.
|
||||
while (pending.length > 0) {
|
||||
const entry = pending.pop()!;
|
||||
if (!isObject(entry.schema)) continue;
|
||||
const scope = references.enter(entry.schema, entry.scope);
|
||||
let seen = sites.get(scope);
|
||||
if (seen === undefined) sites.set(scope, (seen = new WeakSet()));
|
||||
if (seen.has(entry.schema)) continue;
|
||||
seen.add(entry.schema);
|
||||
entries.push({ schema: entry.schema, scope });
|
||||
for (const schema of schemaSubschemas(entry.schema, {
|
||||
includeDefinitions: true,
|
||||
}))
|
||||
pending.push({ schema, scope });
|
||||
}
|
||||
const indexed = new Map<JsonSchemaScope | undefined, WeakMap<object, Fact>>();
|
||||
const work: {
|
||||
schema: Readonly<Record<string, unknown>>;
|
||||
scope: JsonSchemaScope | undefined;
|
||||
fact: Fact;
|
||||
}[] = [];
|
||||
const changed: Fact[] = [];
|
||||
const untracked: Fact[] = [];
|
||||
const factAt = (
|
||||
schema: unknown,
|
||||
inherited: JsonSchemaScope | undefined,
|
||||
): Fact | undefined => {
|
||||
if (!isObject(schema)) return undefined;
|
||||
const scope = references.enter(schema, inherited);
|
||||
let facts = indexed.get(scope);
|
||||
if (facts === undefined) indexed.set(scope, (facts = new WeakMap()));
|
||||
const existing = facts.get(schema);
|
||||
if (existing !== undefined) return existing;
|
||||
const fact: Fact = {
|
||||
changed: false,
|
||||
lostEvaluation: false,
|
||||
dependents: new Set(),
|
||||
evaluationDependents: new Set(),
|
||||
};
|
||||
facts.set(schema, fact);
|
||||
work.push({ schema, scope, fact });
|
||||
return fact;
|
||||
};
|
||||
for (const { schema, scope } of entries) factAt(schema, scope);
|
||||
for (let index = 0; index < work.length; index++) {
|
||||
const { schema, scope, fact } = work[index]!;
|
||||
const ignoresSiblings =
|
||||
scope?.dialect === "draft-07" && typeof schema.$ref === "string";
|
||||
const projection =
|
||||
typeof schema.pattern === "string"
|
||||
? projectPortablePattern(schema.pattern)
|
||||
: undefined;
|
||||
const opaquePatternChanged =
|
||||
!sites.get(scope)?.has(schema) &&
|
||||
projection !== undefined &&
|
||||
(projection.kind !== "exact" || projection.pattern !== schema.pattern);
|
||||
if (
|
||||
!ignoresSiblings &&
|
||||
(opaquePatternChanged ||
|
||||
(sites.get(scope)?.has(schema) && hasWidenedPattern(schema)))
|
||||
) {
|
||||
fact.changed = true;
|
||||
changed.push(fact);
|
||||
}
|
||||
if (typeof schema.$ref === "string") {
|
||||
const target = references.resolve(scope, schema.$ref);
|
||||
if (
|
||||
target.kind === "target" &&
|
||||
!throughRemovableLocation(
|
||||
scope?.root,
|
||||
target.path,
|
||||
scope?.dialect === "draft-07",
|
||||
)
|
||||
) {
|
||||
const dependency = factAt(target.value, scope);
|
||||
dependency?.dependents.add(fact);
|
||||
dependency?.evaluationDependents.add(fact);
|
||||
if (
|
||||
dependency !== undefined &&
|
||||
isObject(target.value) &&
|
||||
!sites.get(references.enter(target.value, scope))?.has(target.value)
|
||||
)
|
||||
fact.opaqueReference = dependency;
|
||||
} else if (target.kind !== "unresolved") {
|
||||
// Named anchors and pointers into removable locations are not
|
||||
// followed by this owner. Relax them when normalizing so a widened or
|
||||
// moved target cannot make a negation stricter or leave a dangling
|
||||
// reference.
|
||||
fact.opaqueReference = fact;
|
||||
if (!fact.changed) {
|
||||
fact.changed = true;
|
||||
changed.push(fact);
|
||||
}
|
||||
} else untracked.push(fact);
|
||||
}
|
||||
if (
|
||||
scope?.dialect !== "draft-07" &&
|
||||
(typeof schema.$dynamicRef === "string" ||
|
||||
typeof schema.$recursiveRef === "string")
|
||||
)
|
||||
untracked.push(fact);
|
||||
if (!ignoresSiblings)
|
||||
for (const child of schemaSubschemas(schema, {
|
||||
includeDefinitions: false,
|
||||
}))
|
||||
factAt(child, scope)?.dependents.add(fact);
|
||||
if (!ignoresSiblings)
|
||||
for (const key of [
|
||||
"allOf",
|
||||
"anyOf",
|
||||
"oneOf",
|
||||
"if",
|
||||
"then",
|
||||
"else",
|
||||
"dependentSchemas",
|
||||
"dependencies",
|
||||
]) {
|
||||
const value = schema[key];
|
||||
const children = Array.isArray(value)
|
||||
? value
|
||||
: schemaMaps.has(key) && isObject(value)
|
||||
? Object.values(value)
|
||||
: [value];
|
||||
for (const child of children)
|
||||
factAt(child, scope)?.evaluationDependents.add(fact);
|
||||
}
|
||||
}
|
||||
// Dynamic targets depend on the evaluation path, and an unresolved target
|
||||
// may be an embedded resource this owner rewrote. Neither is followed, so
|
||||
// once anything widens, relax them like named anchors.
|
||||
if (changed.length > 0)
|
||||
for (const fact of untracked) {
|
||||
fact.opaqueReference = fact;
|
||||
if (!fact.changed) {
|
||||
fact.changed = true;
|
||||
changed.push(fact);
|
||||
}
|
||||
}
|
||||
for (let index = 0; index < changed.length; index++)
|
||||
for (const dependent of changed[index]!.dependents)
|
||||
if (!dependent.changed) {
|
||||
dependent.changed = true;
|
||||
changed.push(dependent);
|
||||
}
|
||||
const lost: Fact[] = [];
|
||||
for (const { schema, scope, fact } of work)
|
||||
if (
|
||||
sites.get(scope)?.has(schema) &&
|
||||
(fact.opaqueReference?.changed ||
|
||||
(!(scope?.dialect === "draft-07" && typeof schema.$ref === "string") &&
|
||||
factAt(schema.if, scope)?.changed))
|
||||
) {
|
||||
fact.lostEvaluation = true;
|
||||
lost.push(fact);
|
||||
}
|
||||
for (let index = 0; index < lost.length; index++)
|
||||
for (const dependent of lost[index]!.evaluationDependents)
|
||||
if (!dependent.lostEvaluation) {
|
||||
dependent.lostEvaluation = true;
|
||||
lost.push(dependent);
|
||||
}
|
||||
return {
|
||||
references,
|
||||
changed: (schema: object, scope: JsonSchemaScope | undefined) =>
|
||||
indexed.get(scope)?.get(schema)?.changed === true,
|
||||
lostEvaluation: (schema: object, scope: JsonSchemaScope | undefined) =>
|
||||
indexed.get(scope)?.get(schema)?.lostEvaluation === true,
|
||||
reduceReference: (schema: object, scope: JsonSchemaScope | undefined) =>
|
||||
indexed.get(scope)?.get(schema)?.opaqueReference?.changed === true,
|
||||
};
|
||||
};
|
||||
|
||||
const normalizeAdvertisedSchema = (
|
||||
value: unknown,
|
||||
context?: ReturnType<typeof normalizationContext>,
|
||||
inherited?: JsonSchemaScope,
|
||||
): SchemaNormalization => {
|
||||
if (!isObject(value)) return { schema: value, changed: false };
|
||||
const owner = context ?? normalizationContext(value);
|
||||
const scope = owner.references.enter(
|
||||
value,
|
||||
context === undefined ? owner.references.rootScope : inherited,
|
||||
);
|
||||
const normalize = (child: unknown) =>
|
||||
normalizeAdvertisedSchema(child, owner, scope);
|
||||
const node: Record<string, unknown> = { ...value };
|
||||
const changed = owner.changed(value, scope);
|
||||
const normalizeMap = (map: Readonly<Record<string, unknown>>) =>
|
||||
Object.fromEntries(
|
||||
Object.entries(map).map(([name, child]) => [
|
||||
name,
|
||||
normalize(child).schema,
|
||||
]),
|
||||
);
|
||||
|
||||
for (const [key, child] of Object.entries(value)) {
|
||||
if (schemaMaps.has(key) && isObject(child)) {
|
||||
node[key] = normalizeMap(child);
|
||||
} else if (
|
||||
schemaArrays.has(key) &&
|
||||
key !== "anyOf" &&
|
||||
key !== "oneOf" &&
|
||||
Array.isArray(child)
|
||||
) {
|
||||
node[key] = child.map(normalize).map((result) => result.schema);
|
||||
} else if (
|
||||
schemaChildren.has(key) &&
|
||||
key !== "not" &&
|
||||
key !== "if" &&
|
||||
key !== "then" &&
|
||||
key !== "else"
|
||||
) {
|
||||
const results = Array.isArray(child)
|
||||
? child.map(normalize)
|
||||
: [normalize(child)];
|
||||
const nestedChanged = results.some((result) => result.changed);
|
||||
if (
|
||||
key === "contains" &&
|
||||
nestedChanged &&
|
||||
value.maxContains !== undefined
|
||||
) {
|
||||
delete node.maxContains;
|
||||
node.contains = results[0]?.schema;
|
||||
} else {
|
||||
node[key] = Array.isArray(child)
|
||||
? results.map((result) => result.schema)
|
||||
: results[0]?.schema;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (typeof node.pattern === "string") {
|
||||
// Clients refuse the complete tools request over one pattern their regex
|
||||
// engine cannot compile. A widened or omitted pattern marks this site
|
||||
// changed, so enclosing `not`, `if` and `oneOf` keep only widening.
|
||||
const projected = projectPortablePattern(node.pattern);
|
||||
if (projected.kind === "unexpressible") delete node.pattern;
|
||||
else node.pattern = projected.pattern;
|
||||
}
|
||||
|
||||
const negated = Object.hasOwn(value, "not")
|
||||
? normalize(value.not)
|
||||
: undefined;
|
||||
if (negated?.changed) {
|
||||
// Widening a predicate under `not` narrows the containing schema.
|
||||
delete node.not;
|
||||
} else if (negated !== undefined) {
|
||||
node.not = negated.schema;
|
||||
}
|
||||
|
||||
const conditional = Object.hasOwn(value, "if")
|
||||
? normalize(value.if)
|
||||
: undefined;
|
||||
const thenBranch = Object.hasOwn(value, "then")
|
||||
? normalize(value.then)
|
||||
: undefined;
|
||||
const elseBranch = Object.hasOwn(value, "else")
|
||||
? normalize(value.else)
|
||||
: undefined;
|
||||
if (conditional?.changed) {
|
||||
// Changing the predicate can route canonical-valid inputs into a rejecting branch.
|
||||
delete node.if;
|
||||
delete node.then;
|
||||
delete node.else;
|
||||
} else {
|
||||
if (conditional !== undefined) node.if = conditional.schema;
|
||||
if (thenBranch !== undefined) {
|
||||
node.then = thenBranch.schema;
|
||||
}
|
||||
if (elseBranch !== undefined) {
|
||||
node.else = elseBranch.schema;
|
||||
}
|
||||
}
|
||||
|
||||
for (const combinator of ["anyOf", "oneOf"] as const) {
|
||||
const branches = value[combinator];
|
||||
if (!Array.isArray(branches)) continue;
|
||||
const normalized = branches.map(normalize);
|
||||
const schemas = normalized.map((result) => result.schema);
|
||||
const branchesChanged = normalized.some((result) => result.changed);
|
||||
if (combinator === "oneOf" && branchesChanged) {
|
||||
// `anyOf` retains branch guidance without allowing widened branches to
|
||||
// reject inputs that were accepted by exactly one canonical branch.
|
||||
delete node.oneOf;
|
||||
if (Array.isArray(node.anyOf)) {
|
||||
const existingAllOf = Array.isArray(node.allOf) ? node.allOf : [];
|
||||
node.allOf = [...existingAllOf, { anyOf: schemas }];
|
||||
} else {
|
||||
node.anyOf = schemas;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
node[combinator] = schemas;
|
||||
}
|
||||
|
||||
if (owner.lostEvaluation(value, scope)) {
|
||||
delete node.unevaluatedProperties;
|
||||
delete node.unevaluatedItems;
|
||||
}
|
||||
if (owner.reduceReference(value, scope)) {
|
||||
// The target is also caller literal data. Keep that data intact and relax
|
||||
// this affected reference rather than copy or mutate its executable view.
|
||||
if (scope?.dialect === "draft-07") {
|
||||
for (const key of Object.keys(node))
|
||||
if (!DRAFT07_REDUCED_REFERENCE_KEYS.has(key)) delete node[key];
|
||||
} else {
|
||||
delete node.$ref;
|
||||
delete node.$dynamicRef;
|
||||
delete node.$recursiveRef;
|
||||
}
|
||||
node.description = [
|
||||
node.description,
|
||||
"This referenced schema is advertised in reduced form; the server validates the complete canonical value.",
|
||||
]
|
||||
.filter((text) => typeof text === "string")
|
||||
.join(" ");
|
||||
}
|
||||
return { schema: node, changed };
|
||||
};
|
||||
|
||||
/**
|
||||
* Present an output schema with portable patterns. SDK clients compile every
|
||||
* listed output schema; literals stay, since no model reads them.
|
||||
*/
|
||||
export const presentOutputJsonSchema = (
|
||||
root: Record<string, unknown>,
|
||||
): Record<string, unknown> => {
|
||||
const patterns = advertisedSchemaPatterns(root).map(({ pattern }) => ({
|
||||
pattern,
|
||||
projection: projectPortablePattern(pattern),
|
||||
}));
|
||||
if (hasLiteralReference(root))
|
||||
return normalizeAdvertisedSchema(root).schema as Record<string, unknown>;
|
||||
// Output schemas reach several megabytes. Exact re-emission changes no
|
||||
// dependent, so only a widened pattern needs the dependency analysis.
|
||||
if (patterns.some(({ projection }) => projection.kind !== "exact"))
|
||||
return normalizeAdvertisedSchema(root).schema as Record<string, unknown>;
|
||||
if (
|
||||
patterns.every(
|
||||
({ pattern, projection }) =>
|
||||
projection.kind === "exact" && projection.pattern === pattern,
|
||||
)
|
||||
)
|
||||
return root;
|
||||
return replaceExactPatterns(root) as Record<string, unknown>;
|
||||
};
|
||||
|
||||
/** A reference into literal data needs dependency analysis, not in-place rewriting. */
|
||||
const hasLiteralReference = (root: Record<string, unknown>): boolean => {
|
||||
const pending: unknown[] = [root];
|
||||
const visited = new WeakSet<object>();
|
||||
while (pending.length > 0) {
|
||||
const value = pending.pop();
|
||||
if (!isObject(value) || visited.has(value)) continue;
|
||||
visited.add(value);
|
||||
if (typeof value.$ref === "string") {
|
||||
try {
|
||||
const reference = decodeURIComponent(value.$ref);
|
||||
if (
|
||||
/(?:^#\/|\/)(?:default|const|enum|examples)(?:\/|$)/u.test(reference)
|
||||
)
|
||||
return true;
|
||||
} catch {
|
||||
// An invalid fragment cannot name one of these locations.
|
||||
}
|
||||
}
|
||||
pending.push(...schemaSubschemas(value, { includeDefinitions: true }));
|
||||
}
|
||||
return false;
|
||||
};
|
||||
|
||||
/** Copy schema positions, replacing each pattern with its exact portable form. */
|
||||
const replaceExactPatterns = (schema: unknown): unknown => {
|
||||
if (!isObject(schema)) return schema;
|
||||
return Object.fromEntries(
|
||||
Object.entries(schema).map(([key, value]) => {
|
||||
if (key === "pattern" && typeof value === "string") {
|
||||
const projection = projectPortablePattern(value);
|
||||
return [key, projection.kind === "exact" ? projection.pattern : value];
|
||||
}
|
||||
if (schemaMaps.has(key) && isObject(value))
|
||||
return [
|
||||
key,
|
||||
Object.fromEntries(
|
||||
Object.entries(value).map(([name, child]) => [
|
||||
name,
|
||||
replaceExactPatterns(child),
|
||||
]),
|
||||
),
|
||||
];
|
||||
if (
|
||||
(schemaArrays.has(key) || schemaChildren.has(key)) &&
|
||||
Array.isArray(value)
|
||||
)
|
||||
return [key, value.map(replaceExactPatterns)];
|
||||
if (schemaChildren.has(key)) return [key, replaceExactPatterns(value)];
|
||||
return [key, value];
|
||||
}),
|
||||
);
|
||||
};
|
||||
@@ -3,11 +3,13 @@ import { Ajv } from "ajv";
|
||||
import { Ajv2020 } from "ajv/dist/2020.js";
|
||||
import { INVALID_BASE64_PADDING_PATTERN } from "../domain/stringPatterns.js";
|
||||
|
||||
import { portablePatternViolations } from "./advertisedDialect.js";
|
||||
import {
|
||||
presentInputJsonSchema,
|
||||
presentOutputJsonSchema,
|
||||
} from "./inputSchemaPresentation.js";
|
||||
ADVERTISED_INPUT_SCHEMA_MAX_BYTES,
|
||||
portablePatternViolations,
|
||||
} from "./advertisedDialect.js";
|
||||
import { advertiseToolInput } from "./advertisedTool.js";
|
||||
import { presentInputJsonSchema } from "./inputSchemaPresentation.js";
|
||||
import { presentOutputJsonSchema } from "./outputSchemaPresentation.js";
|
||||
import { projectPortablePattern } from "./portablePattern.js";
|
||||
|
||||
// Short strings over an alphabet that reaches every class boundary the
|
||||
@@ -216,8 +218,13 @@ describe("portable pattern projection", () => {
|
||||
const PRESENTERS = [
|
||||
[
|
||||
"input",
|
||||
// The input schema a client receives: presentation, then the dialect.
|
||||
(schema: Record<string, unknown>) =>
|
||||
presentInputJsonSchema(schema, () => undefined),
|
||||
advertiseToolInput(
|
||||
undefined,
|
||||
presentInputJsonSchema(schema, () => undefined),
|
||||
{ budgetBytes: ADVERTISED_INPUT_SCHEMA_MAX_BYTES },
|
||||
).inputSchema,
|
||||
],
|
||||
["output", presentOutputJsonSchema],
|
||||
] as const;
|
||||
@@ -231,16 +238,23 @@ describe("advertised pattern presentation", () => {
|
||||
|
||||
it.each(PRESENTERS)(
|
||||
"keeps only widening around a widened %s pattern",
|
||||
(_kind, present) => {
|
||||
(kind, present) => {
|
||||
// Widening a pattern under `not` would narrow the enclosing schema.
|
||||
const negated = present(
|
||||
property({ type: "string", not: { pattern: lookAround } }),
|
||||
);
|
||||
expect(negated).toEqual(property({ type: "string" }));
|
||||
// Exact re-emission keeps the negation.
|
||||
// Exact re-emission keeps an output negation; the advertised input
|
||||
// dialect has no `not`, so the input drops it.
|
||||
expect(
|
||||
present(property({ type: "string", not: { pattern: "^\\d+$" } })),
|
||||
).toEqual(property({ type: "string", not: { pattern: "^[0-9]+$" } }));
|
||||
).toEqual(
|
||||
property(
|
||||
kind === "input"
|
||||
? { type: "string" }
|
||||
: { type: "string", not: { pattern: "^[0-9]+$" } },
|
||||
),
|
||||
);
|
||||
// A widened branch could match alongside a sibling, so `oneOf` becomes `anyOf`.
|
||||
expect(
|
||||
present(
|
||||
@@ -253,6 +267,8 @@ describe("advertised pattern presentation", () => {
|
||||
),
|
||||
).toEqual(
|
||||
property({
|
||||
// The input dialect types a union whose branches share one type.
|
||||
...(kind === "input" ? { type: "string" } : {}),
|
||||
anyOf: [
|
||||
{ type: "string", pattern: "^[a-z]+$" },
|
||||
{ type: "string", pattern: "^con$" },
|
||||
|
||||
@@ -4,6 +4,9 @@ import { describe, expect, it } from "vitest";
|
||||
import { z } from "zod";
|
||||
|
||||
import { applicationFeatureSeedSchema } from "../domain/javascript/javascriptFeatureTraceSchemas.js";
|
||||
import { ADVERTISED_INPUT_SCHEMA_MAX_BYTES } from "./advertisedDialect.js";
|
||||
import { advertiseToolInput } from "./advertisedTool.js";
|
||||
import { presentAdvertisedInput } from "./compactInputSchema.js";
|
||||
import { presentInputJsonSchema } from "./inputSchemaPresentation.js";
|
||||
import { toolContract } from "./toolContracts.js";
|
||||
import {
|
||||
@@ -12,6 +15,14 @@ import {
|
||||
} from "./toolSchemaMetadata.js";
|
||||
import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "./javascript/javascriptRuntimeReconciliationExample.js";
|
||||
|
||||
/** The input schema a client receives: presentation, then the portable dialect. */
|
||||
const advertise = (canonical: Record<string, unknown>) =>
|
||||
advertiseToolInput(
|
||||
undefined,
|
||||
presentInputJsonSchema(canonical, () => undefined),
|
||||
{ budgetBytes: ADVERTISED_INPUT_SCHEMA_MAX_BYTES },
|
||||
).inputSchema;
|
||||
|
||||
it.each(["draft-2020-12", "draft-07"] as const)(
|
||||
"honors projection options independently of cached wire transformations in %s",
|
||||
(target) => {
|
||||
@@ -114,7 +125,7 @@ describe("advertised object dependencies", () => {
|
||||
] as const)(
|
||||
"presents object-group dependencies as guidance without unsupported dialect keywords (%s)",
|
||||
(dialect, dependencyKeyword) => {
|
||||
const advertised = presentInputJsonSchema(
|
||||
const canonical = presentInputJsonSchema(
|
||||
{
|
||||
$schema:
|
||||
dialect === "draft-07"
|
||||
@@ -127,16 +138,15 @@ describe("advertised object dependencies", () => {
|
||||
},
|
||||
() => undefined,
|
||||
);
|
||||
expect(advertised.$schema).toBe(
|
||||
dialect === "draft-07"
|
||||
? "http://json-schema.org/draft-07/schema#"
|
||||
: "https://json-schema.org/draft/2020-12/schema",
|
||||
);
|
||||
expect(advertised).not.toHaveProperty("dependencies");
|
||||
expect(advertised).not.toHaveProperty("dependentRequired");
|
||||
expect(advertised.description).toContain(
|
||||
"When body is provided, also provide url.",
|
||||
);
|
||||
// The registered schema keeps the canonical keyword; the listed schema
|
||||
// states it in the tool guidance instead.
|
||||
expect(canonical).toHaveProperty([dependencyKeyword, "body"], ["url"]);
|
||||
const { schema, guidance } = presentAdvertisedInput(canonical, {
|
||||
budgetBytes: ADVERTISED_INPUT_SCHEMA_MAX_BYTES,
|
||||
});
|
||||
expect(schema).not.toHaveProperty("dependencies");
|
||||
expect(schema).not.toHaveProperty("dependentRequired");
|
||||
expect(guidance).toContain("When body is provided, also provide url.");
|
||||
},
|
||||
);
|
||||
});
|
||||
@@ -430,7 +440,7 @@ const registerBooleanLiteralCompatibilityTests = (): void => {
|
||||
required: ["enabled"],
|
||||
additionalProperties: false,
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = advertise(canonical);
|
||||
const canonicalValidate = new Ajv2020({ strict: false }).compile(canonical);
|
||||
const advertisedValidate = new Ajv2020({ strict: false }).compile(
|
||||
advertised,
|
||||
@@ -450,10 +460,7 @@ const registerBooleanLiteralCompatibilityTests = (): void => {
|
||||
flag: { type: "boolean", not: { const: false } },
|
||||
},
|
||||
};
|
||||
const negatedAdvertisement = presentInputJsonSchema(
|
||||
negated,
|
||||
() => undefined,
|
||||
);
|
||||
const negatedAdvertisement = advertise(negated);
|
||||
const canonicalNegated = new Ajv2020({ strict: false }).compile(negated);
|
||||
const advertisedNegated = new Ajv2020({ strict: false }).compile(
|
||||
negatedAdvertisement,
|
||||
@@ -472,10 +479,7 @@ const registerBooleanLiteralCompatibilityTests = (): void => {
|
||||
},
|
||||
},
|
||||
};
|
||||
const conditionalAdvertisement = presentInputJsonSchema(
|
||||
conditional,
|
||||
() => undefined,
|
||||
);
|
||||
const conditionalAdvertisement = advertise(conditional);
|
||||
const canonicalConditional = new Ajv2020({ strict: false }).compile(
|
||||
conditional,
|
||||
);
|
||||
@@ -505,7 +509,7 @@ describe("advertised client-compatible literals", () => {
|
||||
},
|
||||
},
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = advertise(canonical);
|
||||
expect(
|
||||
new Ajv2020({ strict: false }).compile(canonical)({ value: "" }),
|
||||
).toBe(true);
|
||||
@@ -514,8 +518,6 @@ describe("advertised client-compatible literals", () => {
|
||||
).toBe(true);
|
||||
expect(advertised).toHaveProperty(["properties", "value"], {
|
||||
type: "string",
|
||||
default: "",
|
||||
description: "The literal value.",
|
||||
});
|
||||
},
|
||||
);
|
||||
@@ -532,7 +534,7 @@ describe("advertised client-compatible literals", () => {
|
||||
},
|
||||
},
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = advertise(canonical);
|
||||
const original = new Ajv2020({ strict: false }).compile(canonical);
|
||||
const presented = new Ajv2020({ strict: false }).compile(advertised);
|
||||
for (const value of ["", "named"]) {
|
||||
@@ -594,7 +596,7 @@ describe("advertised Boolean schema composition", () => {
|
||||
},
|
||||
},
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = advertise(canonical);
|
||||
const canonicalValidate = new Ajv2020({ strict: false }).compile(canonical);
|
||||
const advertisedValidate = new Ajv2020({ strict: false }).compile(
|
||||
advertised,
|
||||
@@ -602,7 +604,8 @@ describe("advertised Boolean schema composition", () => {
|
||||
expect(canonicalValidate({ flag: true })).toBe(true);
|
||||
expect(canonicalValidate({ flag: false })).toBe(false);
|
||||
expect(advertisedValidate({ flag: true })).toBe(true);
|
||||
expect(advertised).toHaveProperty(["properties", "flag", "anyOf"]);
|
||||
// A union with an any-value branch accepts every value.
|
||||
expect(advertised).toHaveProperty(["properties", "flag"], {});
|
||||
});
|
||||
|
||||
it("retains nested branch guidance when widening oneOf to anyOf", () => {
|
||||
@@ -633,7 +636,7 @@ describe("advertised Boolean schema composition", () => {
|
||||
},
|
||||
},
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = advertise(canonical);
|
||||
const canonicalValidate = new Ajv2020({ strict: false }).compile(canonical);
|
||||
const advertisedValidate = new Ajv2020({ strict: false }).compile(
|
||||
advertised,
|
||||
@@ -663,7 +666,7 @@ describe("advertised Boolean schema composition", () => {
|
||||
},
|
||||
},
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = advertise(canonical);
|
||||
const canonicalValidate = new Ajv2020({ strict: false }).compile(canonical);
|
||||
const advertisedValidate = new Ajv2020({ strict: false }).compile(
|
||||
advertised,
|
||||
@@ -672,36 +675,9 @@ describe("advertised Boolean schema composition", () => {
|
||||
expect(advertisedValidate({ values: [true] })).toBe(true);
|
||||
expect(advertised).toHaveProperty(["properties", "values"], {
|
||||
type: "array",
|
||||
items: {},
|
||||
});
|
||||
});
|
||||
|
||||
it("normalizes schema keywords only and preserves literal payloads", () => {
|
||||
const literal = {
|
||||
const: false,
|
||||
enum: [false],
|
||||
properties: { nested: { const: true } },
|
||||
};
|
||||
const presented = presentInputJsonSchema(
|
||||
{
|
||||
type: "object",
|
||||
properties: {
|
||||
default: { type: "boolean", const: false },
|
||||
allowed: { enum: [false, true] },
|
||||
kind: { type: "string", const: "exact" },
|
||||
},
|
||||
default: literal,
|
||||
examples: [literal],
|
||||
},
|
||||
() => undefined,
|
||||
);
|
||||
expect(presented.properties).toEqual({
|
||||
default: { type: "boolean" },
|
||||
allowed: { type: "boolean" },
|
||||
kind: { type: "string", const: "exact" },
|
||||
});
|
||||
expect(presented.default).toEqual(literal);
|
||||
expect(presented.examples).toEqual([literal]);
|
||||
});
|
||||
});
|
||||
|
||||
it.each(["draft-2020-12", "draft-07"] as const)(
|
||||
@@ -947,20 +923,15 @@ describe("root union default presentation", () => {
|
||||
});
|
||||
|
||||
describe("advertised empty-string literal edge cases", () => {
|
||||
it("widens empty-string literals under contentSchema", () => {
|
||||
it("drops an empty-string literal under contentSchema", () => {
|
||||
const canonical = {
|
||||
type: "object",
|
||||
properties: {
|
||||
value: { type: "string", contentSchema: { const: "" } },
|
||||
},
|
||||
};
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
expect(advertised.properties).toEqual({
|
||||
value: {
|
||||
type: "string",
|
||||
contentSchema: { type: "string" },
|
||||
},
|
||||
});
|
||||
const advertised = advertise(canonical);
|
||||
expect(advertised.properties).toEqual({ value: { type: "string" } });
|
||||
});
|
||||
|
||||
it("removes the recorded trace seed's empty-string literals from the advertisement", () => {
|
||||
@@ -968,7 +939,7 @@ describe("advertised empty-string literal edge cases", () => {
|
||||
z.strictObject({ seed: applicationFeatureSeedSchema }),
|
||||
{ io: "input", target: "draft-2020-12" },
|
||||
);
|
||||
const advertised = presentInputJsonSchema(canonical, () => undefined);
|
||||
const advertised = advertise(canonical);
|
||||
expect(JSON.stringify(advertised)).not.toContain('"const":""');
|
||||
const canonicalValidate = new Ajv2020({ strict: false }).compile(canonical);
|
||||
const advertisedValidate = new Ajv2020({ strict: false }).compile(
|
||||
|
||||
@@ -6,10 +6,8 @@ import { z } from "zod";
|
||||
|
||||
import type { ToolContract } from "./toolContractTypes.js";
|
||||
import { advertisedInputExamples } from "./advertisedInputExamples.js";
|
||||
import {
|
||||
presentInputJsonSchema,
|
||||
presentOutputJsonSchema,
|
||||
} from "./inputSchemaPresentation.js";
|
||||
import { presentInputJsonSchema } from "./inputSchemaPresentation.js";
|
||||
import { presentOutputJsonSchema } from "./outputSchemaPresentation.js";
|
||||
import {
|
||||
schemaArrays,
|
||||
schemaChildren,
|
||||
@@ -178,7 +176,10 @@ export const toolInputSchemaWithMetadata = <Contract extends ToolContract>(
|
||||
),
|
||||
);
|
||||
|
||||
/** Return the full-profile advertised input JSON Schema registered on MCP. */
|
||||
/**
|
||||
* Return the input JSON Schema registered on MCP. It keeps canonical patterns;
|
||||
* `advertiseToolInput` derives what a client receives from it.
|
||||
*/
|
||||
export const advertisedInputJsonSchema = <Contract extends ToolContract>(
|
||||
contract: Contract,
|
||||
): Record<string, unknown> =>
|
||||
|
||||
@@ -21,10 +21,7 @@ import { EvidenceMcpServer } from "../../../src/server/EvidenceMcpServer.js";
|
||||
import { createToolResultDelivery } from "../../../src/server/toolResult.js";
|
||||
import { toolRegistrationOptions } from "../../../src/server/toolRegistrationOptions.js";
|
||||
import { createTestMcp } from "../../support/mcp/mcpFixture.js";
|
||||
import {
|
||||
arrayItemSchemaError,
|
||||
unsupportedInputLiteralSchemaError,
|
||||
} from "../../fixtures/mcpClientSchemaConstraints.js";
|
||||
import { arrayItemSchemaError } from "../../fixtures/mcpClientSchemaConstraints.js";
|
||||
|
||||
interface AdvertisedTool {
|
||||
readonly name: string;
|
||||
@@ -200,9 +197,8 @@ it("keeps SDK-converted and canonical schemas valid and accepting canonical exam
|
||||
arrayItemSchemaError(tool.inputSchema, tool.name),
|
||||
`${profile} profile: ${tool.name}`,
|
||||
).toBeUndefined();
|
||||
expect(
|
||||
unsupportedInputLiteralSchemaError(tool.inputSchema, tool.name),
|
||||
).toBeUndefined();
|
||||
// Literal portability of the listed schemas is checked with every
|
||||
// other dialect rule in advertisedDialect.test.ts.
|
||||
expect(
|
||||
ajv.validateSchema(tool.inputSchema),
|
||||
`${profile} profile, ${tool.name}: ${ajv.errorsText(ajv.errors)}`,
|
||||
@@ -295,20 +291,19 @@ it("keeps SDK-converted and canonical schemas valid and accepting canonical exam
|
||||
expect(checkedCanonicalRestrictions).toBe(true);
|
||||
});
|
||||
|
||||
it("states dependency keywords as prose in the canonical and compact schemas", async () => {
|
||||
it("states dependency keywords as prose in the listed tool description", async () => {
|
||||
const compact = compactServer();
|
||||
registerCatalog(compact);
|
||||
const compactTools = await listToolsThroughTransport(compact);
|
||||
const sqlite = canonicalTools().find(
|
||||
({ name }) => name === "inspect_sqlite_database",
|
||||
);
|
||||
expect(sqlite?.inputSchema.description).toContain(
|
||||
"When row_limit is provided, also provide table.",
|
||||
// The registered schema keeps the canonical keyword.
|
||||
expect(sqlite?.inputSchema).toHaveProperty(
|
||||
["dependentRequired", "row_limit"],
|
||||
["table"],
|
||||
);
|
||||
expect(sqlite?.inputSchema.description).toContain(
|
||||
"When schema_scope is selected_table, also provide table.",
|
||||
);
|
||||
// Compact moves the sentence to the tool description, which Codex keeps
|
||||
// The listed tool description carries the sentences, which Codex keeps
|
||||
// when it strips descriptions inside a schema above 5,000 bytes.
|
||||
const compactSqlite = compactTools.find(
|
||||
({ name }) => name === "inspect_sqlite_database",
|
||||
@@ -316,6 +311,9 @@ it("states dependency keywords as prose in the canonical and compact schemas", a
|
||||
expect(compactSqlite?.description).toContain(
|
||||
"When schema_scope is selected_table, also provide table.",
|
||||
);
|
||||
expect(compactSqlite?.description).toContain(
|
||||
"When row_limit is provided, also provide table.",
|
||||
);
|
||||
expect(JSON.stringify(compactSqlite?.inputSchema)).not.toContain(
|
||||
"also provide",
|
||||
);
|
||||
|
||||
@@ -6,6 +6,8 @@ import { z } from "zod";
|
||||
|
||||
import { advertisedInputExamples } from "../../../src/contracts/advertisedInputExamples.js";
|
||||
import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js";
|
||||
import { advertiseTool } from "../../../src/contracts/advertisedTool.js";
|
||||
import { advertisedToolPresentation } from "../../../src/config/mcpOutputSchemaProfile.js";
|
||||
import { emptyArraySchema } from "../../../src/domain/emptyArraySchema.js";
|
||||
import { processScenarioSchema } from "../../../src/domain/process/processScenario.js";
|
||||
import {
|
||||
@@ -575,7 +577,12 @@ describe("MCP root input schemas", () => {
|
||||
const tool = advertised.get(name);
|
||||
if (contract === undefined || tool === undefined)
|
||||
throw new Error(`${name} was not advertised`);
|
||||
const validate = ajv.compile(tool.inputSchema);
|
||||
const validate = ajv.compile(
|
||||
advertiseTool(
|
||||
{ inputSchema: tool.inputSchema },
|
||||
advertisedToolPresentation("off"),
|
||||
).inputSchema ?? {},
|
||||
);
|
||||
const base = {
|
||||
cdp_endpoint: "http://127.0.0.1:9222",
|
||||
target_id: "target",
|
||||
@@ -591,7 +598,7 @@ describe("MCP root input schemas", () => {
|
||||
(name === "inspect_web_page" && flag === false);
|
||||
const parsed = contract.inputSchema.safeParse(input);
|
||||
expect(parsed.success, `${name}: ${String(flag)}`).toBe(accepted);
|
||||
// The advertisement relaxes Boolean literals; the canonical parser
|
||||
// The advertised dialect relaxes Boolean literals; the canonical parser
|
||||
// still rejects false when this operation requires script sources.
|
||||
expect(validate(input), `${name}: ${String(flag)}`).toBe(
|
||||
flag === undefined || typeof flag === "boolean",
|
||||
|
||||
+7
-16
@@ -5,10 +5,7 @@ import {
|
||||
schemaChildren as schemaChildKeywords,
|
||||
schemaMaps as schemaMapKeywords,
|
||||
} from "../../src/contracts/jsonSchemaKeywords.js";
|
||||
import {
|
||||
arrayItemSchemaError,
|
||||
unsupportedInputLiteralSchemaError,
|
||||
} from "./mcpClientSchemaConstraints.js";
|
||||
import { arrayItemSchemaError } from "./mcpClientSchemaConstraints.js";
|
||||
|
||||
/** Advertised schema pair as a client receives it from `tools/list`. */
|
||||
interface AdvertisedToolSchemas {
|
||||
@@ -18,11 +15,12 @@ interface AdvertisedToolSchemas {
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate advertised schemas as clients receive them: Ajv's declared-dialect
|
||||
* meta-schema and reference resolution, then the constraints a real client
|
||||
* enforces. Compiling catches a compact projection that drops a referenced
|
||||
* definition or leaves a local `$ref` without its target, which a byte-budget
|
||||
* assertion alone would not.
|
||||
* Validate registered schemas: Ajv's declared-dialect meta-schema and
|
||||
* reference resolution, then array `items`. Compiling catches a projection
|
||||
* that drops a referenced definition or leaves a local `$ref` without its
|
||||
* target, which a byte-budget assertion alone would not. Literal portability
|
||||
* belongs to the advertised dialect projection, so it is checked on the
|
||||
* schemas a served catalog lists, not here.
|
||||
*/
|
||||
export function advertisedSchemaErrors(
|
||||
tools: readonly AdvertisedToolSchemas[],
|
||||
@@ -52,13 +50,6 @@ export function advertisedSchemaErrors(
|
||||
`${tool.name}.${kind}`,
|
||||
);
|
||||
if (clientError !== undefined) return [clientError];
|
||||
if (kind === "inputSchema") {
|
||||
const literalError = unsupportedInputLiteralSchemaError(
|
||||
schema,
|
||||
`${tool.name}.${kind}`,
|
||||
);
|
||||
if (literalError !== undefined) return [literalError];
|
||||
}
|
||||
return [];
|
||||
} catch (cause: unknown) {
|
||||
return [
|
||||
|
||||
Reference in new issue
Block a user