refactor: migrate validators to TypeBox by steipete · Pull Request #86639 · openclaw/openclaw

steipete · 2026-05-25T21:24:47Z

Summary

migrate shared/plugin, gateway protocol, Codex app-server, and Lobster wrapper validation from direct Ajv compilation to TypeBox
remove root/Codex/Lobster direct Ajv dependency pins while keeping the Lobster embedded-runtime Ajv content cache for @clawdbot/lobster's current transitive Ajv usage
preserve JSON Schema defaults/ref behavior, conditional default semantics, URI-only format validation, non-uri format annotations, draft-2020 dynamic refs, nullable compatibility, and structured validation diagnostics

Verification

pnpm test src/config/config.plugin-validation.test.ts src/config/validation.policy.test.ts src/gateway/server.auth.default-token.test.ts src/gateway/protocol/index.test.ts src/plugins/schema-validator.test.ts src/agents/pi-bundle-mcp-runtime.test.ts -- --reporter=verbose
env -u OPENCLAW_TESTBOX -u OPENCLAW_TESTBOX_REMOTE_RUN pnpm check:changed
.agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main
post-rebase repeat of the same test/check gate and autoreview against latest origin/main

Real behavior proof

Behavior addressed: Direct Ajv validator usage is removed from root/Codex/Lobster-owned validation paths while TypeBox preserves plugin/config/MCP JSON Schema behavior.
Real environment tested: Local macOS checkout on branch refactor/typebox-validators, rebased onto origin/main at 2e17003165.
Exact steps or command run after this patch: pnpm test src/config/config.plugin-validation.test.ts src/config/validation.policy.test.ts src/gateway/server.auth.default-token.test.ts src/gateway/protocol/index.test.ts src/plugins/schema-validator.test.ts src/agents/pi-bundle-mcp-runtime.test.ts -- --reporter=verbose; env -u OPENCLAW_TESTBOX -u OPENCLAW_TESTBOX_REMOTE_RUN pnpm check:changed; .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main.
Evidence after fix: Focused validator/config/gateway/MCP shards passed; check:changed passed; autoreview reported no accepted/actionable findings.
Observed result after fix: TypeBox validates the migrated surfaces, preserves Ajv-compatible defaults/ref/nullable/dynamic-ref behavior covered by regression tests, and rejects malformed externally supplied schemas.
What was not tested: Full release packaging or live external MCP server execution beyond the local MCP runtime validator coverage.

github-actions · 2026-05-25T21:24:54Z

Dependency Changes Detected

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

extensions/codex/npm-shrinkwrap.json
extensions/codex/package.json
extensions/lobster/npm-shrinkwrap.json
extensions/lobster/package.json
npm-shrinkwrap.json
package.json
pnpm-lock.yaml

Maintainer follow-up:

Review whether the dependency changes are intentional.
Inspect resolved package deltas when lockfile, shrinkwrap, or workspace dependency policy changes are present.
Treat package-lock.json and npm-shrinkwrap.json diffs as security-review surfaces.
Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

clawsweeper · 2026-05-25T21:27:01Z

Codex review: needs real behavior proof before merge. Reviewed May 25, 2026, 11:29 PM ET / 03:29 UTC.

Summary
The PR migrates plugin/config, gateway protocol, Codex app-server, bundled MCP, and Lobster validation from Ajv to TypeBox while updating tests and dependency manifests.

PR surface: Source +1371, Tests +1652, Config -1, Other -3. Total +3019 across 31 files.

Reproducibility: not applicable. this is a refactor PR, not a bug report. Current-main evidence shows the central validator surfaces still use Ajv, so the PR is active rather than obsolete.

Review metrics: 2 noteworthy metrics.

Validator runtime surfaces: 4 migrated: plugin/config, gateway protocol, Codex app-server, bundled MCP/Lobster. The migration crosses compatibility-sensitive validation boundaries where green unit tests may not cover all existing schemas.
Direct dependency manifest deltas: Root swaps 1, Codex swaps 1, Lobster removes 1. Package ownership and shrinkwrap changes are install and supply-chain review surfaces before merge.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🧂 unranked krab
Patch quality: 🐚 platinum hermit
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Add redacted terminal/live output or logs from a real plugin config, gateway, Codex, MCP, or Lobster validation path after this patch.
Record maintainer dependency review for the root, Codex, Lobster, lockfile, and shrinkwrap deltas.

Proof guidance:
Needs real behavior proof before merge: Missing: the PR body lists tests/checks only; add redacted terminal/live output or logs from a real validator, gateway, plugin, Codex, or Lobster path, then update the PR body to trigger re-review.

Risk before merge

This replaces validator engines across plugin config, gateway protocol, Codex app-server, MCP draft-2020-12, and Lobster paths, so small Ajv/TypeBox semantic differences can affect existing plugin schemas, gateway clients, or runtime validation.
The package and shrinkwrap changes alter direct dependency ownership for the root, Codex, and Lobster packages; maintainers should explicitly accept those dependency deltas before merge.
The PR has the protected maintainer label and lacks contributor real behavior proof, so this should stay human-handled even with no current line-level findings.

Maintainer options:

Prove validator parity and dependency intent (recommended)
Add redacted real run output from at least one plugin/config or gateway/Codex/Lobster runtime path and record maintainer acceptance of the package and shrinkwrap deltas.
Accept the test-only refactor risk
A maintainer can intentionally merge after deciding the targeted tests and type/check output are enough for this broad validator-engine swap.

Next step before merge
Maintainer review is the next action because this protected-label PR has dependency and validator compatibility risk plus missing contributor real behavior proof rather than a narrow repair defect.

Security
Cleared: No concrete secret-handling or executable-download regression was identified, but the lockfile and shrinkwrap dependency changes remain maintainer review surfaces.

Review details

Best possible solution:

Land only after maintainers accept the dependency and validator-parity risk and the contributor adds redacted real runtime proof; otherwise keep the Ajv-backed implementation until a narrower parity migration is ready.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a refactor PR, not a bug report. Current-main evidence shows the central validator surfaces still use Ajv, so the PR is active rather than obsolete.

Is this the best way to solve the issue?

Unclear: the TypeBox approach is plausible and covered by targeted tests, but the merge-ready solution still needs real runtime proof and an explicit dependency-review record because validator and package contracts changed together.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 17ab9b967c63.

Label changes

Label justifications:

P2: This is a broad refactor with limited direct user-facing blast radius but meaningful validator and dependency compatibility risk.
merge-risk: 🚨 compatibility: Merging can change accepted/rejected schemas and package dependency behavior across existing plugin, gateway, Codex, MCP, and Lobster users.
rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Missing: the PR body lists tests/checks only; add redacted terminal/live output or logs from a real validator, gateway, plugin, Codex, or Lobster path, then update the PR body to trigger re-review.

Evidence reviewed

PR surface:

Source +1371, Tests +1652, Config -1, Other -3. Total +3019 across 31 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	13	1664	293	+1371
Tests	13	1824	172	+1652
Docs	0	0	0	0
Config	3	2	3	-1
Generated	0	0	0	0
Other	2	7	10	-3
Total	31	3497	478	+3019

What I checked:

Current main still uses Ajv on the central validator path: Current main imports Ajv in the plugin schema validator, so this PR is not obsolete on main. (src/plugins/schema-validator.ts:1, 17ab9b967c63)
PR migrates plugin schema validation to TypeBox: The PR branch imports TypeBox Compile/Format and uses TypeBox validators for validateJsonSchemaValue. (src/plugins/schema-validator.ts:1, 3a1b860eaa4d)
PR migrates gateway protocol validators: Gateway protocol lazy validators now compile schemas through TypeBox and expose TypeBox-shaped errors. (src/gateway/protocol/index.ts:442, 3a1b860eaa4d)
PR preserves MCP and Lobster validator paths with new TypeBox/Ajv split: Draft-2020-12 MCP schemas use TypeBox while Lobster still installs a package-local Ajv compile cache before importing the embedded runtime. (src/agents/pi-bundle-mcp-runtime.ts:133, 3a1b860eaa4d)
Dependency manifests change direct runtime dependencies: The root manifest swaps direct Ajv for photon-node, Codex swaps Ajv for TypeBox, and Lobster removes its direct Ajv dependency while keeping TypeBox. (package.json:1820, 3a1b860eaa4d)
Upstream TypeBox contract checked: TypeBox 1.1.38 Compile returns a Validator, and the Format registry is process-global with Format.Set/Test behavior, which makes validation parity and import-order proof relevant.

Likely related people:

steipete: Recent current-main history shows package/dependency and Codex app-server adjacent work, so this route is relevant beyond authoring this PR. (role: recent adjacent contributor; confidence: medium; commits: bee8ad34a011, 6f5728667861; files: extensions/codex/src/app-server/run-attempt.test.ts, package.json, pnpm-lock.yaml)
vincentkoc: The shallow current-main history blames the existing validator, gateway protocol, MCP, and Lobster files to the repository root/import commit; this is a routing signal, not blame. (role: current-main history owner signal; confidence: low; commits: 2a6b4ed3e2ab; files: src/plugins/schema-validator.ts, src/gateway/protocol/index.ts, src/agents/pi-bundle-mcp-runtime.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

clawsweeper · 2026-05-25T21:37:06Z

ClawSweeper PR egg

🎁 Pass real behavior proof to wake the egg and unlock a hatchable treat.

Where did the egg go?

The egg game starts only after the PR passes the real-behavior proof check.
Before that, no creature or rarity is rolled. The treat waits for real proof.
This is still just collectible flavor: proof affects review readiness, not creature quality.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e75d924543

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-26T03:03:41Z

 export async function loadEmbeddedToolRuntimeFromPackage(
  options: LoadEmbeddedToolRuntimeFromPackageOptions = {},
 ): Promise<EmbeddedToolRuntime> {
-  installLobsterAjvCompileCache();
-
  const importModule =
    options.importModule ??


Reinstall Lobster Ajv compile cache before runtime import

loadEmbeddedToolRuntimeFromPackage no longer installs the Lobster Ajv compile cache before importing @clawdbot/lobster, which removes the content-hash/LRU dedup guard that previously bounded compiled-schema growth. Because the bundled Lobster runtime still depends on Ajv (extensions/lobster/npm-shrinkwrap.json), repeated tool calls that produce equivalent-but-new schema objects can now accumulate validators and increase memory/compile overhead over time in long-lived sessions.

Useful? React with 👍 / 👎.

socket-security · 2026-05-26T03:23:16Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/@lancedb/lancedb@0.29.0
	npm/@google/genai@2.6.0
	npm/@grammyjs/transformer-throttler@1.2.1
	npm/@create-markdown/preview@2.0.3
	npm/@copilotkit/aimock@1.27.1
	npm/@grammyjs/runner@2.0.3
	npm/@lydell/node-pty@1.2.0-beta.12
	npm/@line/bot-sdk@11.0.0
	npm/@lit/context@1.1.6
	npm/@lit-labs/signals@0.3.0
	npm/@grammyjs/types@3.27.3
	npm/@azure/identity@4.13.1
	npm/@anthropic-ai/vertex-sdk@0.16.1
	npm/@homebridge/ciao@1.3.8
	npm/@aws-sdk/client-bedrock@3.1053.0
	npm/@aws-sdk/client-s3@3.1053.0
	npm/@aws-sdk/s3-request-presigner@3.1053.0

View full report

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3a1b860eaa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-26T03:30:02Z

+  const packageEntryPath = resolvePackageEntry("@clawdbot/lobster");
+  await installLobsterAjvCompileCache(packageEntryPath);


Defer package entry resolution until fallback import

Calling resolvePackageEntry("@clawdbot/lobster") before attempting the primary @clawdbot/lobster/core import introduces an early-fail path: if package-root resolution throws (for example when only the core subpath is resolvable or a custom loader is used), runtime loading now aborts before trying the primary import route that previously ran first. This is a behavior regression in loadEmbeddedToolRuntimeFromPackage and can break environments where core is loadable but root resolution is not.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4977d52c4f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-26T07:47:05Z

+      if (key === "$dynamicRef" && normalizedSchema.$ref === undefined) {
+        return ["$ref", value];


Preserve $dynamicRef semantics in normalized schemas

Rewriting $dynamicRef to $ref here changes draft-2020-12 behavior from dynamic to static reference resolution, so schemas that rely on dynamic anchor rebinding (for example recursive/extensible tool-output schemas from external MCP catalogs) can validate differently than before this refactor. The previous implementation used Ajv 2020-12 support directly, but createBundleMcpJsonSchemaValidator now compiles normalized schemas through this helper, so this conversion can cause valid payloads to be rejected (or invalid ones accepted) whenever $dynamicRef and $dynamicAnchor are used beyond trivial local cases.

Useful? React with 👍 / 👎.

* refactor: migrate validators to typebox * fix: preserve json schema resource refs * chore: clean schema preflight recursion * refactor: remove lobster ajv shim * fix: support schema array refs * fix: validate schema dependencies * fix: preserve schema contract checks * fix: support same-document schema refs * fix: preserve untyped map defaults * fix: preserve schema default semantics * test: avoid thenable schema literals * test: build conditional schema key * fix: defer resource id refs to typebox * fix: reject invalid schema enum metadata * fix: preserve default branch semantics * fix: resolve schema resource refs * fix: narrow conditional default fallback * fix: preserve uri format validation * fix: preserve validator compatibility * test: avoid ajv cache lint violation * fix: preserve typebox validation diagnostics * fix: validate defaulted conditional schemas * fix: normalize mcp draft schemas * fix: preserve tuple schema defaults * fix: resolve relative schema refs * fix: scope typebox format semantics * fix: align conditional format defaults * fix: decode schema pointer refs * fix: filter grouped secretref diagnostics * fix: preserve default conditional compatibility * fix: preserve nullable schema compatibility * fix: settle defaults before conditionals * fix: preserve default validation invariants * fix: validate dynamic schema refs * fix: reject malformed nullable schemas

steipete requested a review from a team as a code owner May 25, 2026 21:24

github-actions Bot added the dependencies-changed PR changes dependency-related files label May 25, 2026

openclaw-barnacle Bot added app: web-ui App: web-ui gateway Gateway runtime agents Agent runtime and tooling channel: twitch Channel integration: twitch extensions: memory-wiki extensions: codex extensions: diffs size: XL maintainer Maintainer-authored PR labels May 25, 2026

steipete force-pushed the refactor/typebox-validators branch from 4e6b08c to e75d924 Compare May 26, 2026 02:55

openclaw-barnacle Bot added the extensions: lobster Extension: lobster label May 26, 2026

chatgpt-codex-connector Bot reviewed May 26, 2026

View reviewed changes

steipete force-pushed the refactor/typebox-validators branch from e75d924 to 3a1b860 Compare May 26, 2026 03:22

chatgpt-codex-connector Bot reviewed May 26, 2026

View reviewed changes

steipete added 6 commits May 26, 2026 08:28

refactor: migrate validators to typebox

ac82968

fix: preserve json schema resource refs

cc51f23

chore: clean schema preflight recursion

931d00f

refactor: remove lobster ajv shim

5c19825

fix: support schema array refs

25a98a3

fix: validate schema dependencies

a3fabaf

steipete added 21 commits May 26, 2026 08:28

fix: preserve default branch semantics

dcc6877

fix: resolve schema resource refs

4e929f0

fix: narrow conditional default fallback

0c6d303

fix: preserve uri format validation

f51007f

fix: preserve validator compatibility

f1ab5ea

test: avoid ajv cache lint violation

b233f48

fix: preserve typebox validation diagnostics

b48e26f

fix: validate defaulted conditional schemas

81f05ad

fix: normalize mcp draft schemas

a068f8b

fix: preserve tuple schema defaults

f2ce954

fix: resolve relative schema refs

daac031

fix: scope typebox format semantics

5f296a7

fix: align conditional format defaults

1f7b450

fix: decode schema pointer refs

ae48b1c

fix: filter grouped secretref diagnostics

0bfb47d

fix: preserve default conditional compatibility

fb5bb55

fix: preserve nullable schema compatibility

c60c94f

fix: settle defaults before conditionals

56fb19c

fix: preserve default validation invariants

921b15c

fix: validate dynamic schema refs

e269ea8

fix: reject malformed nullable schemas

4977d52

steipete force-pushed the refactor/typebox-validators branch from 3a1b860 to 4977d52 Compare May 26, 2026 07:38

steipete merged commit 3548cff into main May 26, 2026
105 checks passed

steipete deleted the refactor/typebox-validators branch May 26, 2026 07:45

chatgpt-codex-connector Bot reviewed May 26, 2026

View reviewed changes

clawsweeper Bot mentioned this pull request Jun 2, 2026

fix(shared): harden JSON schema default traversal #89630

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor: migrate validators to TypeBox#86639

refactor: migrate validators to TypeBox#86639
steipete merged 35 commits into
mainfrom
refactor/typebox-validators

steipete commented May 25, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 25, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 25, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 25, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 26, 2026

Uh oh!

socket-security Bot commented May 26, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 26, 2026

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		const packageEntryPath = resolvePackageEntry("@clawdbot/lobster");
		await installLobsterAjvCompileCache(packageEntryPath);

		if (key === "$dynamicRef" && normalizedSchema.$ref === undefined) {
		return ["$ref", value];

Uh oh!

Conversation

steipete commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Real behavior proof

Uh oh!

github-actions Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Changes Detected

Uh oh!

clawsweeper Bot commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clawsweeper Bot commented May 25, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 26, 2026

Choose a reason for hiding this comment

Uh oh!

socket-security Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

steipete commented May 25, 2026 •

edited

Loading

github-actions Bot commented May 25, 2026 •

edited

Loading

clawsweeper Bot commented May 25, 2026 •

edited

Loading

socket-security Bot commented May 26, 2026 •

edited

Loading