PR #66137: fix(ajv): validate MCP tool schemas against draft/2020-12 [AI-assisted]

• Repository: openclaw/openclaw
• Author: secondfry
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/66137

Description (problem / solution / changelog)

Summary

Fixes the no schema with key or ref "https://json-schema.org/draft/2020-12/schema" family of errors reported across browser tools and external MCP servers. There are four Ajv compile sites that need draft/2020-12 support; three are in openclaw source, the fourth is in a pinned dep:

1. src/gateway/protocol/index.ts — gateway protocol schemas
2. src/plugins/schema-validator.ts — plugin config + channel schemas (validateJsonSchemaValue)
3. extensions/llm-task/src/llm-task-tool.ts — user-supplied LLM output schema
4. @mariozechner/pi-ai/dist/utils/validation.js — per-call validateToolArguments, runs for every tool invocation through @mariozechner/pi-agent-core's agent loop

All four migrate from default ajv (draft-07-only meta) to ajv/dist/2020.js with addMetaSchema(draft-07) so both dialects compile. The fourth site is covered two ways: a pnpm patch on @mariozechner/[email protected] (so source builds and pnpm installs are correct), and an in-place hotfix in scripts/postinstall-bundled-plugins.mjs (so npm i -g openclaw@latest users — who don't honor pnpm.patchedDependencies — also get the fix; pi-ai is not bundled into openclaw's dist/, so without the postinstall hook the patch wouldn't ship to production at all). The hotfix follows the existing baileys pattern: atomic write, mode preservation, path-escape guards, marker-based idempotency.

Why this path (research summary)

1. Traced the user-visible error from the Python MCP server: pydantic v2's GenerateJsonSchema.schema_dialect emits $schema: "https://json-schema.org/draft/2020-12/schema" on every inputSchema. Same story for zod-emitted browser/playwright tool schemas (target: "draft-2020-12").
2. Verified empirically: default Ajv throws no schema with key or ref "https://json-schema.org/draft/2020-12/schema" at compile, regardless of strict: false (which only silences unknown-keyword warnings — it does not suppress $schema URI resolution).
3. Rejected the inverse (default Ajv + addMetaSchema(draft-2020-12)): the 2020-12 meta is multi-file and throws MissingRefError: can't resolve reference meta/core; even if patched around, default Ajv silently ignores 2020-12-only keywords (prefixItems, unevaluatedProperties, $dynamicRef) under strict: false — which is the same silent-correctness bug, reframed.
4. Ajv2020 + addMetaSchema(draft-07) is the correct direction. Ajv2020 implements every draft-07 keyword in use (dependencies verified to produce the exact keyword: 'dependencies' / params.missingProperty shape schema-validator.ts:98 consumes; definitions, $defs, object/string/number constraints all identical). The one draft-07 shape Ajv2020 hard-rejects — tuple items: [...] — was grep-confirmed absent from every internal schema fed into Ajv across src/, extensions/, and the 486 KB bundled-channel-config-metadata.generated.ts. additionalItems, $recursiveRef, $recursiveAnchor likewise absent. If a contributor ever introduces tuple items, Ajv2020 fails loudly (items value must be ["object","boolean"]) rather than silently miscompiling — strictly safer.
5. The fourth site (pi-ai) is the actual hot path — validateToolArguments runs on every tool call. #65798's reporter applied the openclaw-side fix manually and saw "improved but not eliminated" because the per-tool-call validator inside the pinned dep was still default Ajv. Tracing from src/agents/pi-bundle-mcp-materialize.ts:104 (parameters: tool.inputSchema) into pi-agent-core's agent-loop.js:301 led to pi-ai/dist/utils/validation.js; both the pnpm patch and the postinstall hotfix exist to cover the same site across both install paths.
6. Considered and rejected per-$schema dispatch in llm-task: tried it, then realized any unlabeled-default choice has a failure mode (Ajv2020-default loud-fails on tuple items; draft-07-default silently miscompiles 2020-12-only keywords on unlabeled MCP schemas — re-introducing the original bug). Reverted; single-instance Ajv2020 + draft-07 meta is the only design without a dialect-routing footgun. (Discussion lives in the resolved P2 review threads.)

Closes #58560 Closes #61863 Closes #65798

Note: #58084 is not closed by this PR. That's an emission-side issue — Anthropic's draft/2020-12 validator rejects schemas openclaw sends (likely anchored patternProperties or TypeBox tuple items). The fix belongs in src/agents/pi-tools.schema.ts / src/agents/pi-embedded-runner/anthropic-family-tool-payload-compat.ts, not here.

Test plan

• pnpm tsgo — no new type errors; pre-existing failures in telegram/whatsapp/cron/wizard reproduce on clean main via git stash
• pnpm build:plugin-sdk:dts — succeeds (ajv/dist/2020.js specifier required for NodeNext; [email protected] has no exports map)
• pnpm test -- src/plugins/schema-validator.test.ts src/gateway/protocol/*.test.ts src/secrets/exec-secret-ref-id-parity.test.ts — 55 green
• pnpm test -- src/mcp/plugin-tools-serve.test.ts src/gateway/mcp-http.test.ts extensions/memory-wiki/src/config.test.ts — green
• Empirical: real draft-07 schema from bundled-channel-config-metadata.generated.ts compiles/validates correctly; draft/2020-12 schema with unevaluatedProperties: false correctly rejects extras
• Empirical on the patched pi-ai: validateToolCall accepts both draft-07 and draft/2020-12 tools, including 2020-12 unevaluatedProperties rejection
• Postinstall hotfix idempotency: simulated unpatched input → applied; rerun → already_patched; restore → clean
• Live production smoke-test: built openclaw-2026.4.14.tgz from this branch (pnpm install && pnpm build && pnpm ui:build && OPENCLAW_PREPACK_PREPARED=1 pnpm pack), installed on the author's production server via npm i -g ./openclaw-2026.4.14.tgz, confirmed the postinstall hotfix applied (@mariozechner/pi-ai/dist/utils/validation.js now imports ajv/dist/2020.js and registers the draft-07 meta-schema), and verified the fix works against a real MCP surface — tool invocations that previously threw no schema with key or ref "https://json-schema.org/draft/2020-12/schema" now succeed.
• extensions/diffs/src/config.test.ts viewer-asset failures, src/agents/pi-bundle-mcp-runtime.test.ts MCP-process flakes, and llm-task Windows mkdtemp failures all verified pre-existing on clean main

CI status (red checks pre-exist on main)

CI is mostly green: 29 passing, 6 skipping, 6 failing. The 6 failing jobs are pre-existing failures on main or PR-required-by-design comparisons — none caused by this PR. Per CONTRIBUTING.md lines 116–117, these aren't ours to fix.

All Ajv- and pi-ai-touching jobs pass: check, build-artifacts, build-smoke, checks-node-core-src, checks-node-core-security, checks-node-extensions-shard-1..6, extension-fast-llm-task, install-smoke, security-fast, actionlint, no-tabs, etc.

AI-assisted

• Mark as AI-assisted: yes (Claude Code / Opus 4.6)
• Degree of testing: fully tested end-to-end — typecheck, targeted vitest, empirical Ajv checks through the pi-ai entrypoint against both dialects, postinstall hotfix idempotency simulation, and a live production smoke-test on the author's npm-installed server (see Test plan).
• I understand the code: yes — four-site Ajv2020 + addMetaSchema(draft-07) migration; pi-ai vendored dep covered via pnpm patch and postinstall string-replace hotfix to bridge the npm-install gap; rationale and tradeoffs above.
• Session logs: available on request.
• All five codex-connector review threads on this PR have been replied to and resolved.

Changed files

• extensions/llm-task/src/llm-task-tool.ts (modified, +9/-1)
• package.json (modified, +2/-1)
• patches/@[email protected] (added, +22/-0)
• pnpm-lock.yaml (modified, +7/-4)
• scripts/postinstall-bundled-plugins.mjs (modified, +140/-3)
• src/gateway/protocol/index.ts (modified, +12/-1)
• src/plugins/schema-validator.ts (modified, +8/-1)