Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
perf(mcp): share repeated output schema definitions
Ysopwnable441813c0708d
diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.mdindex 5a8b92de3..e2b0c5eac 100644--- a/docs/mcp-contracts.md+++ b/docs/mcp-contracts.md@@ -31,6 +31,10 @@ check the complete catalog after SDK conversion and its generated counterpart.This is REA's local compatibility profile; individual model APIs can imposeadditional limits.+Output schemas share repeated definitions through local references while+preserving their complete fields and validation rules. Canonical Zod validation+and the input compatibility profile continue to apply.+For passive `compare_web_captures` inputs, pass each complete`inspect_web_page` result in `before.inspection` or `after.inspection`, with anoptional complete `discover_webmcp_tools` result in the matching `webmcp` field.diff --git a/src/contracts/toolOutputReferences.test.ts b/src/contracts/toolOutputReferences.test.tsnew file mode 100644index 000000000..587393473--- /dev/null+++ b/src/contracts/toolOutputReferences.test.ts@@ -0,0 +1,177 @@+import { Ajv } from "ajv";+import { Ajv2020 } from "ajv/dist/2020.js";+import { expect, it } from "vitest";+import { z } from "zod";++import { inlineLocalJsonSchemaReferences } from "../../tests/fixtures/localJsonSchemaReferences.js";+import { toolContract } from "./toolContracts.js";+import { toolOutputSchemaWithMetadata } from "./toolSchemaMetadata.js";++it.each(["draft-2020-12", "draft-07"] as const)(+ "preserves refined numeric bounds and strict repeated objects through %s references",+ (target) => {+ const integer = z.number().int().nonnegative();+ const range = z+ .object({+ offset: integer.max(65535),+ length: integer.min(1),+ exclusive: integer.positive(),+ })+ .strict();+ const canonical = z.object({ before: range, after: range }).strict();+ const advertised = toolOutputSchemaWithMetadata({+ ...toolContract("open_binary"),+ outputSchema: canonical,+ })["~standard"].jsonSchema.output({ target });+ const ajv =+ target === "draft-2020-12"+ ? new Ajv2020({ strict: false })+ : new Ajv({ strict: false });+ const validate = ajv.compile(advertised);+ const valid = {+ before: { offset: 0, length: 1, exclusive: 1 },+ after: { offset: 65535, length: 9007199254740991, exclusive: 1 },+ };+ const samples: readonly unknown[] = [+ valid,+ ...[+ { offset: -1 },+ { offset: 65536 },+ { offset: 0.5 },+ { length: 0 },+ { length: 9007199254740992 },+ { exclusive: 0 },+ { exclusive: -1 },+ { length: null },+ { unexpected: true },+ ].map((change) => ({ ...valid, before: { ...valid.before, ...change } })),+ { ...valid, before: { offset: 0, exclusive: 1 } },+ { ...valid, after: null },+ { ...valid, unexpected: true },+ ];+ expect(canonical.safeParse(valid).success).toBe(true);+ for (const sample of samples)+ expect(validate(sample)).toBe(canonical.safeParse(sample).success);+ expect(inlineLocalJsonSchemaReferences(advertised)).toEqual(+ inlineLocalJsonSchemaReferences(+ canonical["~standard"].jsonSchema.output({ target }),+ ),+ );+ },+);++it("keeps schema data containing reference-shaped objects untouched", () => {+ const literal = { $ref: "https://example.invalid/value" };+ const expanded = inlineLocalJsonSchemaReferences({+ $defs: {+ "a/b": {+ type: "object",+ properties: { $defs: { const: literal } },+ examples: [literal],+ },+ },+ $ref: "#/$defs/a~1b",+ description: "Keep the caller-facing annotation",+ });+ expect(expanded).toEqual({+ type: "object",+ properties: { $defs: { const: literal } },+ examples: [literal],+ description: "Keep the caller-facing annotation",+ });+});++it.each(["draft-2020-12", "draft-07"] as const)(+ "preserves layered native-selector string patterns through %s references",+ (target) => {+ const selector = z+ .string()+ .min(1)+ .regex(/^[^\0]*$/u)+ .regex(/^[^\s[\]]+$/u);+ const canonical = z.object({ before: selector, after: selector }).strict();+ const advertised = toolOutputSchemaWithMetadata({+ ...toolContract("open_binary"),+ outputSchema: canonical,+ })["~standard"].jsonSchema.output({ target });+ const ajv =+ target === "draft-2020-12"+ ? new Ajv2020({ strict: false })+ : new Ajv({ strict: false });+ const validate = ajv.compile(advertised);+ for (const value of [+ "setFoo:",+ "dataTaskWithRequest:completionHandler:",+ "",+ "set\0Foo:",+ "bad selector:",+ "bad[selector]:",+ ]) {+ const sample = { before: value, after: "setFoo:" };+ expect(validate(sample)).toBe(canonical.safeParse(sample).success);+ }+ expect(inlineLocalJsonSchemaReferences(advertised)).toEqual(+ inlineLocalJsonSchemaReferences(+ canonical["~standard"].jsonSchema.output({ target }),+ ),+ );+ },+);++it("rejects unresolved and cyclic references rather than concealing schema drift", () => {+ expect(() =>+ inlineLocalJsonSchemaReferences({ $ref: "#/$defs/missing" }),+ ).toThrow("Missing schema reference");+ expect(() =>+ inlineLocalJsonSchemaReferences({+ $defs: { loop: { $ref: "#/$defs/loop" } },+ $ref: "#/$defs/loop",+ }),+ ).toThrow("Recursive schema reference");+});++it("intersects referenced numeric bounds and rejects conflicting validation keywords", () => {+ expect(+ inlineLocalJsonSchemaReferences({+ $defs: { bounded: { type: "number", minimum: 1, maximum: 10 } },+ $ref: "#/$defs/bounded",+ minimum: 0,+ maximum: 9,+ }),+ ).toEqual({ type: "number", minimum: 1, maximum: 9 });+ expect(() =>+ inlineLocalJsonSchemaReferences({+ $defs: { strict: { type: "object" } },+ $ref: "#/$defs/strict",+ type: "string",+ }),+ ).toThrow("Conflicting schema reference sibling: type");+});++it("preserves strict-object evaluation scope across references and singleton intersections", () => {+ const strict = {+ type: "object",+ properties: { value: { type: "string" } },+ additionalProperties: false,+ };+ const schemas = [+ {+ $defs: { strict },+ $ref: "#/$defs/strict",+ additionalProperties: false,+ },+ { allOf: [strict], additionalProperties: false },+ ];+ for (const schema of schemas) {+ const expanded = z+ .record(z.string(), z.unknown())+ .parse(inlineLocalJsonSchemaReferences(schema));+ const ajv = new Ajv2020({ strict: false });+ const original = ajv.compile(schema);+ const normalized = ajv.compile(expanded);+ expect(original({})).toBe(true);+ expect(original({ value: "kept" })).toBe(false);+ for (const sample of [{}, { value: "kept" }, { unexpected: true }, null])+ expect(normalized(sample)).toBe(original(sample));+ }+});diff --git a/src/contracts/toolSchemaMetadata.test.ts b/src/contracts/toolSchemaMetadata.test.tsindex f5f6d491e..391282bfe 100644--- a/src/contracts/toolSchemaMetadata.test.ts+++ b/src/contracts/toolSchemaMetadata.test.ts@@ -1,5 +1,6 @@import { describe, expect, it } from "vitest";+import { inlineLocalJsonSchemaReferences } from "../../tests/fixtures/localJsonSchemaReferences.js";import { TOOL_CONTRACTS, toolContract } from "./toolContracts.js";import {toolInputSchemaWithMetadata,@@ -19,8 +20,13 @@ describe("advertised tool JSON Schema", () => {expect(advertisedInput.examples, contract.name).toEqual(contract.examples.map(({ input: example }) => example),);- expect(advertisedOutput, contract.name).toEqual(- contract.outputSchema["~standard"].jsonSchema.output({ target }),+ expect(+ inlineLocalJsonSchemaReferences(advertisedOutput),+ contract.name,+ ).toEqual(+ inlineLocalJsonSchemaReferences(+ contract.outputSchema["~standard"].jsonSchema.output({ target }),+ ),);}});@@ -34,4 +40,46 @@ describe("advertised tool JSON Schema", () => {expect(latest.$schema).toBe("https://json-schema.org/draft/2020-12/schema");expect(draft07.$schema).toBe("http://json-schema.org/draft-07/schema#");});++ it("preserves complete output meaning across JSON Schema dialects", () => {+ for (const dialect of ["draft-2020-12", "draft-07"] as const)+ for (const contract of TOOL_CONTRACTS) {+ const advertised = toolOutputSchemaWithMetadata(contract)[+ "~standard"+ ].jsonSchema.output({ target: dialect });+ const canonical = contract.outputSchema["~standard"].jsonSchema.output({+ target: dialect,+ });+ expect(+ inlineLocalJsonSchemaReferences(advertised),+ contract.name,+ ).toEqual(inlineLocalJsonSchemaReferences(canonical));+ }+ });++ it("retains memoization and explicit caller projection options", () => {+ const contract = toolContract("analyze_javascript_application");+ const output =+ toolOutputSchemaWithMetadata(contract)["~standard"].jsonSchema;+ const shared = output.output({ target });+ expect(shared.$defs).toBeDefined();+ expect(output.output({ target })).toBe(shared);+ const options = { target, libraryOptions: { reused: "inline" } };+ const inline = output.output(options);+ expect(inline).toEqual(+ contract.outputSchema["~standard"].jsonSchema.output(options),+ );+ expect(inline.$defs).toBeUndefined();+ expect(output.output({ target })).toBe(shared);+ const draft07 = output.output({ target: "draft-07" });+ expect(draft07.$schema).toBe("http://json-schema.org/draft-07/schema#");+ expect(inlineLocalJsonSchemaReferences(draft07)).toEqual(+ inlineLocalJsonSchemaReferences(+ contract.outputSchema["~standard"].jsonSchema.output({+ target: "draft-07",+ }),+ ),+ );+ expect(output.output({ target: "draft-07" })).toBe(draft07);+ });});diff --git a/src/contracts/toolSchemaMetadata.ts b/src/contracts/toolSchemaMetadata.tsindex bed9526ba..3a845a9ba 100644--- a/src/contracts/toolSchemaMetadata.ts+++ b/src/contracts/toolSchemaMetadata.ts@@ -63,11 +63,19 @@ export const toolInputSchemaWithMetadata = <Contract extends ToolContract>(}),);-/** Advertise a canonical output schema without reconverting it per listing. */+/** Share repeated output definitions without changing canonical validation. */export const toolOutputSchemaWithMetadata = <Contract extends ToolContract>(contract: Contract,): Contract["outputSchema"] =>- withAdvertisedJsonSchema(contract.outputSchema, "output");+ withAdvertisedJsonSchema(+ contract.outputSchema,+ "output",+ (project) => (options) =>+ project({+ ...options,+ libraryOptions: { reused: "ref", ...options.libraryOptions },+ }),+ );const withAdvertisedJsonSchema = <Schema extends z.ZodType>(canonical: Schema,diff --git a/tests/boundary/mcp/outputSchemaSemanticConstraints.test.ts b/tests/boundary/mcp/outputSchemaSemanticConstraints.test.tsindex 84d87dfea..c7dbb95ed 100644--- a/tests/boundary/mcp/outputSchemaSemanticConstraints.test.ts+++ b/tests/boundary/mcp/outputSchemaSemanticConstraints.test.ts@@ -17,6 +17,7 @@ import {import { nativeUiResultSchema } from "../../../src/domain/native/nativeUiObservation.js";import { processCaptureSchema } from "../../../src/domain/process/processCapture.js";import { toolRegistrationOptions } from "../../../src/server/toolRegistrationOptions.js";+import { inlineLocalJsonSchemaReferences } from "../../fixtures/localJsonSchemaReferences.js";const record = (value: unknown): Record<string, unknown> => {if (typeof value !== "object" || value === null || Array.isArray(value))@@ -66,7 +67,7 @@ it("advertises semantic output invariants and keeps producers aligned with Zod",: { $defs: outputSchema.$defs }),});return {- result,+ result: record(inlineLocalJsonSchemaReferences(standaloneResultSchema)),validate: new Ajv2020({strict: false,validateFormats: false,diff --git a/tests/fixtures/localJsonSchemaReferences.ts b/tests/fixtures/localJsonSchemaReferences.tsnew file mode 100644index 000000000..aa8efdf13--- /dev/null+++ b/tests/fixtures/localJsonSchemaReferences.ts@@ -0,0 +1,170 @@+const schemaMaps = new Set([+ "properties",+ "patternProperties",+ "dependentSchemas",+]);+const schemaArrays = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);+const schemaChildren = new Set([+ "items",+ "additionalItems",+ "contains",+ "additionalProperties",+ "unevaluatedProperties",+ "unevaluatedItems",+ "propertyNames",+ "not",+ "if",+ "then",+ "else",+]);+const lowerBounds = new Set(["minimum", "exclusiveMinimum"]);+const upperBounds = new Set(["maximum", "exclusiveMaximum"]);+const scopedKeywords = new Set([+ "properties",+ "patternProperties",+ "additionalProperties",+ "items",+ "additionalItems",+ "prefixItems",+ "contains",+ "unevaluatedProperties",+ "unevaluatedItems",+]);++const record = (value: unknown): value is Record<string, unknown> =>+ typeof value === "object" && value !== null && !Array.isArray(value);++/** Inline finite local references for representation-independent schema assertions. */+export const inlineLocalJsonSchemaReferences = (+ root: Readonly<Record<string, unknown>>,+): unknown => {+ const resolve = (reference: string): Record<string, unknown> => {+ if (!reference.startsWith("#/"))+ throw new Error(`Expected a local schema reference: ${reference}`);+ let current: unknown = root;+ for (const encoded of reference.slice(2).split("/")) {+ const key = encoded.replaceAll("~1", "/").replaceAll("~0", "~");+ if (!record(current) || !Object.hasOwn(current, key))+ throw new Error(`Missing schema reference: ${reference}`);+ current = current[key];+ }+ if (!record(current))+ throw new Error(`Expected a referenced schema object: ${reference}`);+ return current;+ };++ const visit = (value: unknown, active: ReadonlySet<string>): unknown => {+ if (!record(value)) return value;+ if (typeof value.$ref === "string") {+ const { $ref: reference, ...siblings } = value;+ if (active.has(reference))+ throw new Error(`Recursive schema reference: ${reference}`);+ const referenced = resolve(reference);+ // Keep declarations in their original evaluation scope.+ if (Object.keys(siblings).some((key) => scopedKeywords.has(key)))+ return {+ allOf: [+ visit(referenced, new Set([...active, reference])),+ visit(siblings, active),+ ],+ };+ const merged = { ...referenced, ...siblings };+ for (const [key, entry] of Object.entries(siblings)) {+ const previous = referenced[key];+ if (+ previous === undefined ||+ JSON.stringify(previous) === JSON.stringify(entry)+ )+ continue;+ if (typeof previous === "number" && typeof entry === "number") {+ if (lowerBounds.has(key)) {+ merged[key] = Math.max(previous, entry);+ continue;+ }+ if (upperBounds.has(key)) {+ merged[key] = Math.min(previous, entry);+ continue;+ }+ }+ throw new Error(`Conflicting schema reference sibling: ${key}`);+ }+ return visit(merged, new Set([...active, reference]));+ }+ if (Array.isArray(value.allOf) && value.allOf.length === 1) {+ const child = visit(value.allOf[0], active);+ const { allOf: _allOf, ...siblings } = value;+ if (+ record(child) &&+ !Object.keys(siblings).some((key) => scopedKeywords.has(key)) &&+ Object.entries(siblings).every(+ ([key, entry]) =>+ child[key] === undefined ||+ JSON.stringify(child[key]) === JSON.stringify(entry) ||+ (typeof child[key] === "number" &&+ typeof entry === "number" &&+ (lowerBounds.has(key) || upperBounds.has(key))),+ )+ ) {+ const merged = { ...child, ...siblings };+ for (const [key, entry] of Object.entries(siblings)) {+ const previous = child[key];+ if (typeof previous !== "number" || typeof entry !== "number")+ continue;+ if (lowerBounds.has(key)) merged[key] = Math.max(previous, entry);+ else if (upperBounds.has(key))+ merged[key] = Math.min(previous, entry);+ }+ return visit(merged, active);+ }+ }+ const normalized = { ...value };+ if (+ typeof normalized.pattern === "string" &&+ Array.isArray(normalized.allOf) &&+ normalized.allOf.some(+ (child: unknown) =>+ record(child) && child.pattern === normalized.pattern,+ )+ )+ delete normalized.pattern;+ if (+ typeof normalized.minimum === "number" &&+ typeof normalized.exclusiveMinimum === "number" &&+ normalized.exclusiveMinimum >= normalized.minimum+ )+ delete normalized.minimum;+ if (+ typeof normalized.maximum === "number" &&+ typeof normalized.exclusiveMaximum === "number" &&+ normalized.exclusiveMaximum <= normalized.maximum+ )+ delete normalized.maximum;+ return Object.fromEntries(+ Object.entries(normalized)+ .filter(([key]) => key !== "$defs" && key !== "definitions")+ .map(([key, child]) => {+ if (schemaMaps.has(key) && record(child))+ return [+ key,+ Object.fromEntries(+ Object.entries(child).map(([name, schema]) => [+ name,+ visit(schema, active),+ ]),+ ),+ ];+ if (schemaArrays.has(key) && Array.isArray(child))+ return [key, child.map((schema) => visit(schema, active))];+ if (schemaChildren.has(key))+ return [+ key,+ Array.isArray(child)+ ? child.map((schema) => visit(schema, active))+ : visit(child, active),+ ];+ return [key, child];+ }),+ );+ };+ return visit(root, new Set());+};