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:
morluto authored and GitHub committed 2026-11-16 03:55:27 +08:00
1 parent 3d22f0041a
commit b0e0d52a9f
15 files changed
+726 -810

No files matched your search

+2 -1
View File
@@ -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 -1
View File
@@ -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);
};
+33 -14
View File
@@ -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);
}
}
},
);
+5 -1
View File
@@ -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,
};
+4 -4
View File
@@ -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);
+10 -645
View File
@@ -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;
};
+515
View File
@@ -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];
}),
);
};
+24 -8
View File
@@ -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$" },
+36 -65
View File
@@ -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 -5
View File
@@ -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
View File
@@ -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 [