@devries-cameron20 / composio-1 / commits / 26315ead2
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(json-schema-to-effect-schema): reject dynamic-key schema defects at construction

@cfworker/json-schema compiles patternProperties keys and resolves $ref lazily, inside validate. A defect in the schema therefore surfaced once per call through the same channel as a genuine input failure, telling the caller their arguments were wrong when the tool's schema was broken. Check both eagerly, scoped to what the Python SDK rejects while wrapping a tool: patternProperties keys, and references inside a patternProperties or schema-valued additionalProperties subschema, followed transitively through the schemas they resolve to. References elsewhere stay with the interpreter, so a dangling reference in a branch validation never visits keeps working. The filter keeps its catch for the one throw that depends on the instance rather than the schema - a bigint, symbol, function, or undefined input. Rethrowing from there would escape Schema.decodeUnknown as a defect instead of a typed parse error.

jkomyno committed Aug 7, 2026 at 22:41 UTC 26315ead21dc9b9913b0ea006b4a46cab9d9df1f
2 files changed +243 -1
ts/packages/json-schema-to-effect-schema/src/index.ts
+103 -1
@@ -1,4 +1,4 @@
1 -import { Validator } from '@cfworker/json-schema';
1 +import { dereference, Validator } from '@cfworker/json-schema';
2 import type { OutputUnit, Schema as InterpreterSchema, SchemaDraft } from '@cfworker/json-schema';
3 import { Schema } from 'effect';
4
@@ -188,6 +188,102 @@ const normalizeSchemaNode = (
188 const normalizeJsonSchema = (schema: JsonObject): InterpreterSchema =>
189 normalizeSchemaNode(schema, new WeakMap()) as InterpreterSchema;
190
191 +// Walks the same child positions `normalizeSchemaNode` does, so a node is
192 +// visited exactly where the interpreter would descend into it.
193 +const forEachSchemaNode = (
194 + value: unknown,
195 + seen: WeakSet<object>,
196 + visit: (node: JsonObject) => void
197 +): void => {
198 + if (!isJsonObject(value) || seen.has(value)) {
199 + return;
200 + }
201 + seen.add(value);
202 + visit(value);
203 +
204 + for (const [key, child] of Object.entries(value)) {
205 + if (schemaMapKeywords.has(key) && isJsonObject(child)) {
206 + for (const nested of Object.values(child)) {
207 + forEachSchemaNode(nested, seen, visit);
208 + }
209 + } else if (schemaArrayKeywords.has(key) && Array.isArray(child)) {
210 + for (const nested of child) {
211 + forEachSchemaNode(nested, seen, visit);
212 + }
213 + } else if (schemaValueKeywords.has(key)) {
214 + for (const nested of Array.isArray(child) ? child : [child]) {
215 + forEachSchemaNode(nested, seen, visit);
216 + }
217 + }
218 + }
219 +};
220 +
221 +const assertRegexCompiles = (pattern: string, keyword: string): void => {
222 + try {
223 + // The same flag `@cfworker/json-schema` compiles with, so this accepts
224 + // exactly the patterns the interpreter would.
225 + new RegExp(pattern, 'u');
226 + } catch (cause) {
227 + throw new Error(`Invalid ${keyword} regular expression ${JSON.stringify(pattern)}.`, { cause });
228 + }
229 +};
230 +
231 +// Follows every reference reachable from one dynamic-key subschema, including
232 +// through the schemas those references resolve to, so a local pointer whose
233 +// target carries a dangling reference is caught as well.
234 +const assertDynamicReferencesResolve = (
235 + subSchema: unknown,
236 + lookup: Record<string, unknown>,
237 + seen: WeakSet<object>
238 +): void => {
239 + forEachSchemaNode(subSchema, seen, node => {
240 + const ref = node.$ref;
241 + if (typeof ref !== 'string') {
242 + return;
243 + }
244 +
245 + const absolute = (node as { readonly __absolute_ref__?: string }).__absolute_ref__ ?? ref;
246 + const target = lookup[absolute];
247 + if (target === undefined) {
248 + throw new Error(`Unresolved $ref ${JSON.stringify(ref)} in a dynamic-key schema.`);
249 + }
250 +
251 + assertDynamicReferencesResolve(target, lookup, seen);
252 + });
253 +};
254 +
255 +// `@cfworker/json-schema` compiles `patternProperties` keys and resolves `$ref`
256 +// lazily, inside `validate`. Left alone, a defect in the schema surfaces once
257 +// per call through the same channel as a genuine input failure, telling the
258 +// caller their arguments are wrong when the tool's schema is what is broken.
259 +// Checking eagerly moves those defects to construction, where the CLI already
260 +// reports them as a compile failure against the cached schema path.
261 +//
262 +// The scope matches what the Python SDK rejects while wrapping a tool: the keys
263 +// of `patternProperties`, and references inside a dynamic-key subschema. A
264 +// reference in a declared property is deliberately left to the interpreter —
265 +// widening past parity would reject tool schemas that validate today.
266 +const assertSchemaIsInterpretable = (schema: InterpreterSchema): void => {
267 + // Re-derives the lookup the `Validator` keeps private. `dereference` builds a
268 + // fresh map per call and reuses the `__absolute_ref__` it already stamped, so
269 + // running it a second time is consistent with the interpreter's own view.
270 + const lookup = dereference(schema);
271 +
272 + forEachSchemaNode(schema, new WeakSet(), node => {
273 + const patternProperties = node.patternProperties;
274 + if (isJsonObject(patternProperties)) {
275 + for (const [pattern, patternSchema] of Object.entries(patternProperties)) {
276 + assertRegexCompiles(pattern, 'patternProperties');
277 + assertDynamicReferencesResolve(patternSchema, lookup, new WeakSet());
278 + }
279 + }
280 +
281 + if (isJsonObject(node.additionalProperties)) {
282 + assertDynamicReferencesResolve(node.additionalProperties, lookup, new WeakSet());
283 + }
284 + });
285 +};
286 +
287 const decodePointer = (pointer: string): ReadonlyArray<string> => {
288 if (pointer === '#' || pointer === '') {
289 return [];
@@ -356,6 +452,7 @@ export const jsonSchemaToEffectSchema = (
452 ): Schema.Schema<unknown> => {
453 const normalizedSchema = normalizeJsonSchema(jsonSchema);
454 const validator = new Validator(normalizedSchema, options.draft ?? '7', false);
455 + assertSchemaIsInterpretable(normalizedSchema);
456 const formatIssues = options.formatIssues ?? defaultFormatIssues;
457
458 return Schema.Unknown.pipe(
@@ -364,6 +461,11 @@ export const jsonSchemaToEffectSchema = (
461 try {
462 validation = validator.validate(input);
463 } catch (error) {
464 + // Schema defects are rejected at construction, so what reaches here is
465 + // input the interpreter cannot represent at all — a `bigint`, `symbol`,
466 + // `function`, or `undefined`. That is a property of the input, so it
467 + // belongs in the filter. A string is `Schema.filter`'s shorthand for the
468 + // `ParseResult.Type` issue Effect would otherwise build by hand.
469 return `JSON Schema validation failed: ${error}`;
470 }
471 if (validation.valid) {
ts/packages/json-schema-to-effect-schema/test/json-schema-to-effect-schema.test.ts
+140
@@ -141,3 +141,143 @@ describe('shared cross-SDK object corpus', () => {
141 });
142 }
143 });
144 +
145 +describe('schema defects fail at construction', () => {
146 + // `@cfworker/json-schema` resolves references and compiles regexes inside
147 + // `validate`, so each of these used to reach the caller once per call, as an
148 + // input validation failure. The consumer wraps construction in its own
149 + // `Effect.try` and reports a compile failure against the cached schema path,
150 + // which is the accurate diagnosis for all of them.
151 + const defects: ReadonlyArray<readonly [string, JsonSchema, RegExp]> = [
152 + [
153 + 'an invalid patternProperties regular expression',
154 + { type: 'object', patternProperties: { '[': { type: 'string' } } },
155 + /Invalid patternProperties regular expression/,
156 + ],
157 + [
158 + 'an invalid patternProperties regular expression nested under a property',
159 + {
160 + type: 'object',
161 + properties: { a: { type: 'object', patternProperties: { '(': { type: 'string' } } } },
162 + },
163 + /Invalid patternProperties regular expression/,
164 + ],
165 + [
166 + 'an invalid patternProperties regular expression inside array items',
167 + {
168 + type: 'object',
169 + properties: {
170 + a: { type: 'array', items: { type: 'object', patternProperties: { '(?<': {} } } },
171 + },
172 + },
173 + /Invalid patternProperties regular expression/,
174 + ],
175 + [
176 + 'an unresolved local $ref in a patternProperties subschema',
177 + { type: 'object', patternProperties: { '^s_': { $ref: '#/$defs/Missing' } } },
178 + /Unresolved \$ref .* in a dynamic-key schema/,
179 + ],
180 + [
181 + 'an external $ref in a patternProperties subschema',
182 + { type: 'object', patternProperties: { '^s_': { $ref: 'https://example.com/s.json' } } },
183 + /Unresolved \$ref .* in a dynamic-key schema/,
184 + ],
185 + [
186 + 'an unresolved local $ref in a schema-valued additionalProperties',
187 + { type: 'object', additionalProperties: { $ref: '#/$defs/Missing' } },
188 + /Unresolved \$ref .* in a dynamic-key schema/,
189 + ],
190 + [
191 + 'a dynamic-key reference whose target carries a dangling reference',
192 + {
193 + type: 'object',
194 + additionalProperties: { $ref: '#/$defs/Hop' },
195 + $defs: { Hop: { type: 'object', properties: { a: { $ref: '#/$defs/Missing' } } } },
196 + },
197 + /Unresolved \$ref .* in a dynamic-key schema/,
198 + ],
199 + [
200 + 'a duplicate schema URI',
201 + {
202 + $id: 'https://example.com/a',
203 + type: 'object',
204 + $defs: { x: { $id: 'https://example.com/a', type: 'string' } },
205 + },
206 + /Duplicate schema URI/,
207 + ],
208 + ];
209 +
210 + // Deliberately outside the scope above: matching the Python SDK, which only
211 + // rejects dynamic-key schemas while wrapping a tool. Widening to every `$ref`
212 + // would reject tool schemas whose dangling reference sits in a branch the
213 + // interpreter never descends into, and which validate today.
214 + const toleratedOutsideDynamicKeys: ReadonlyArray<readonly [string, JsonSchema]> = [
215 + [
216 + 'an unresolved $ref under a declared property',
217 + { type: 'object', properties: { a: { $ref: '#/$defs/Missing' } } },
218 + ],
219 + [
220 + 'an unresolved $ref inside array items',
221 + { type: 'object', properties: { a: { type: 'array', items: { $ref: '#/$defs/Gone' } } } },
222 + ],
223 + [
224 + 'an invalid pattern regular expression',
225 + { type: 'object', properties: { a: { type: 'string', pattern: '[' } } },
226 + ],
227 + ];
228 +
229 + for (const [label, schema] of toleratedOutsideDynamicKeys) {
230 + it(`leaves ${label} to the interpreter`, () => {
231 + expect(() => jsonSchemaToEffectSchema(schema)).not.toThrow();
232 + });
233 + }
234 +
235 + for (const [label, schema, message] of defects) {
236 + it(`rejects ${label}`, () => {
237 + expect(() => jsonSchemaToEffectSchema(schema)).toThrow(message);
238 + });
239 + }
240 +
241 + it('resolves a local $ref that does exist', () => {
242 + const schema = {
243 + type: 'object',
244 + properties: { a: { $ref: '#/$defs/Name' } },
245 + required: ['a'],
246 + $defs: { Name: { type: 'string' } },
247 + } satisfies JsonSchema;
248 +
249 + expect(() => jsonSchemaToEffectSchema(schema)).not.toThrow();
250 + expect(effectAccepts(schema, { a: 'Ada' })).toBe(true);
251 + expect(effectAccepts(schema, { a: 1 })).toBe(false);
252 + });
253 +
254 + it('accepts a self-referential $ref without re-entering it', () => {
255 + const schema = {
256 + type: 'object',
257 + properties: { next: { $ref: '#' } },
258 + } satisfies JsonSchema;
259 +
260 + expect(() => jsonSchemaToEffectSchema(schema)).not.toThrow();
261 + expect(effectAccepts(schema, { next: { next: {} } })).toBe(true);
262 + });
263 +});
264 +
265 +describe('input the interpreter cannot represent stays an input failure', () => {
266 + // The one throw in `validate` that depends on the instance rather than the
267 + // schema. It must stay inside the filter: throwing here would escape
268 + // `Schema.decodeUnknown` as a defect instead of a typed parse error.
269 + const unrepresentable: ReadonlyArray<readonly [string, unknown]> = [
270 + ['a bigint', BigInt(1)],
271 + ['a function', () => 1],
272 + ['a symbol', Symbol('x')],
273 + ['undefined', undefined],
274 + ];
275 +
276 + for (const [label, input] of unrepresentable) {
277 + it(`rejects ${label} without throwing`, () => {
278 + const schema = jsonSchemaToEffectSchema({ type: 'object' });
279 + expect(() => Schema.decodeUnknownOption(schema)(input)).not.toThrow();
280 + expect(Option.isSome(Schema.decodeUnknownOption(schema)(input))).toBe(false);
281 + });
282 + }
283 +});