Sweep legacy tool parameter schemas after PR #1900 normalizer removal

[chubes4]

Summary

PR #1900 ("Require canonical AI tool schemas") removed RequestBuilder::normalizeToolParameters auto-normalization, but did not sweep DM's own tool registrations. Multiple core handlers and tools still emit the legacy property-keyed shape ({name => {type, required: true|false, description}}) which now fails OpenAI provider validation post-0.106.1.

Affected scopes

Three distinct buckets, all using the same legacy shape, all need the same canonical conversion ({type: object, properties: {...}, required: [...]}):

1. Chat tools (inc/Api/Chat/Tools/)

~30 files. Each getToolDefinition() returns a parameters block in legacy property-keyed shape. Spot-checked:

• CreatePipeline.php
• ManageQueue.php, ListFlows.php, AssignTaxonomyTerm.php, GetProblemFlows.php, ReorderPipelineSteps.php, GetHandlerDefaults.php, SetHandlerDefaults.php, ConfigurePipelineStep.php, SendPing.php, DeleteFlow.php, AddPipelineStep.php, DeleteFile.php, UpdateFlow.php, DeletePipeline.php, CreateFlow.php, CreateTaxonomyTerm.php, ReadLogs.php, MergeTaxonomyTerms.php, ManageJobs.php, DeletePipelineStep.php, ExecuteWorkflowTool.php, SearchTaxonomyTerms.php, SystemHealthCheck.php, AuthenticateHandler.php, ConfigureFlowSteps.php, ManageLogs.php, UpdateTaxonomyTerm.php, ApiQuery.php, CopyFlow.php, RunFlow.php

2. Global AI tools (inc/Engine/AI/Tools/Global/)

7 files. Some may be settings-UI rather than tool schemas — needs per-file verification:

• BingWebmaster.php, AmazonAffiliateLink.php, GoogleSearchConsole.php, GoogleSearch.php, ImageGeneration.php, GoogleAnalytics.php, PageSpeed.php

3. Handler tool registrations (inc/Core/Steps/Publish/Handlers/)

2 files. Same pattern as the just-fixed data-machine-events/EventUpsertFilters (Extra-Chill/data-machine-events#235):

• WordPress/WordPress.php — wordpress_publish tool, lines ~47–80; merges with TaxonomyHandler::getTaxonomyToolParameters() output
• Email/Email.php — email_publish tool, lines ~45–70

Out of scope (do NOT touch)

These also use required: true|false but legitimately, per WordPress conventions:

• inc/Api/** (non-Chat) — WP REST API args definitions consumed by register_rest_route(). Property-level required is the official WP REST contract.
• inc/Core/Steps/**Settings.php, inc/Core/Steps/**Auth.php, inc/Core/Steps/SystemTask/SystemTaskSettings.php — DM's own settings-UI form field defs, separate convention.
• inc/Abilities/** input/output schemas — these follow the WP Abilities API spec and are consumed by abilities, not sent to OpenAI directly. Any change here needs a separate audit (filed as follow-up).

Conversion rules

Identical to the rules used in Extra-Chill/data-machine-events#232 and #235:

1. Wrap properties under { 'type' => 'object', 'properties' => array(...), 'required' => array(...) }.
2. Move every property where required => true into the top-level required[] string list.
3. Drop required => false entirely (no-op).
4. Omit required key if no required properties (don't emit empty array).
5. Every type: array property must declare items (OpenAI strict mode requirement). Use items: { type: object } for structured items, items: { type: string } for string lists.
6. Preserve all other property keys (description, enum, etc.).

For the handler-tool registrations in scope 3, the merge logic also needs adjusting — TaxonomyHandler::getTaxonomyToolParameters() already returns shape-compatible bare-properties (no required flags, items present on arrays), so the registration site can wrap the merged result in the canonical envelope without touching TaxonomyHandler itself.

Backwards compatibility

Canonical schemas are accepted by both DM 0.103.x (passthrough via the still-present normalizer in older versions) and DM 0.106.1+ (passthrough literal). Safe to merge ahead of any deploy.

Proposed dispatch

Three parallel PRs from three minions, one per scope above. Tracked by this issue.

Why now

Blocks DM 0.106.1 deploy on extrachill.com. Will block deploy on every site using these handlers/tools.

References

• DM PR Require canonical AI tool schemas #1900 (the change that removed the normalizer)
• fix(tools): canonical JSON Schema for chat tools data-machine-events#232 (chat tools precedent — merged)
• fix(upsert): canonical JSON Schema for handler tool registrations data-machine-events#235 (handler-tool merge precedent — merged)

[chubes4]

Scope 2 (inc/Engine/AI/Tools/Global/) is already canonical — no PR needed

Investigated all 7 files in this scope. All getToolDefinition() parameters blocks are already in canonical JSON Schema form as of PR #1900 itself (commit c6449e08).

PR #1900's own diff swept the Global/ tool directory in addition to flipping the normalizer:

inc/Engine/AI/Tools/Global/AgentDailyMemory.php    | 28 ++++++++----------
inc/Engine/AI/Tools/Global/AgentMemory.php         | 22 +++++++-------
inc/Engine/AI/Tools/Global/AmazonAffiliateLink.php |  7 +++--
inc/Engine/AI/Tools/Global/BingWebmaster.php       | 13 +++++----
inc/Engine/AI/Tools/Global/GoogleAnalytics.php     | 34 +++++++++-------------
inc/Engine/AI/Tools/Global/GoogleSearch.php        | 10 ++++---
inc/Engine/AI/Tools/Global/GoogleSearchConsole.php | 31 +++++++++-----------
inc/Engine/AI/Tools/Global/ImageGeneration.php     | 16 +++++-----
inc/Engine/AI/Tools/Global/InternalLinkAudit.php   | 28 ++++++++----------
inc/Engine/AI/Tools/Global/LocalSearch.php         | 13 +++++----
inc/Engine/AI/Tools/Global/PageSpeed.php           | 13 +++++----
inc/Engine/AI/Tools/Global/QueueValidator.php      | 19 ++++++------
inc/Engine/AI/Tools/Global/WebFetch.php            |  7 +++--
inc/Engine/AI/Tools/Global/WordPressPostReader.php | 10 ++++---

Per-file verification

File	Tool schema status	Settings-UI required:true|false (out of scope, untouched)
BingWebmaster.php	✅ Canonical (type: object, properties: {...}, required: ['action'])	2 (in get_config_fields())
AmazonAffiliateLink.php	✅ Canonical (required: ['query'])	4 (in get_config_fields())
GoogleSearchConsole.php	✅ Canonical (required: ['action'])	2 (in get_config_fields())
GoogleSearch.php	✅ Canonical (required: ['query'])	2 (in get_config_fields())
ImageGeneration.php	✅ Canonical (required: ['prompt'])	5 (in get_config_fields())
GoogleAnalytics.php	✅ Canonical (required: ['action'])	2 (in get_config_fields())
PageSpeed.php	✅ Canonical (required: ['action'])	1 (in get_config_fields())

All settings-UI required flags live in get_config_fields() methods which feed the DM admin form renderer, not OpenAI. Per the original ticket's "Out of scope" section ("DM's own settings-UI form field defs, separate convention"), they correctly stay as booleans.

type: array audit (OpenAI strict-mode items requirement)

grep -n "'type' *=> *'array'" inc/Engine/AI/Tools/Global/*.php returns:

• InternalLinkAudit.php:130 — has items: { type: 'string' } ✅
• LocalSearch.php:80 — has items: { type: 'string' } ✅

Neither in this scope-2 list, but both already compliant.

Tests

tests/Unit/Engine/AI/Tools/Global/BingWebmasterTest.php and ImageGenerationTest.php already assert the canonical shape:

$this->assertSame( 'object', $def['parameters']['type'] );
$this->assertSame( array( 'action' ), $def['parameters']['required'] );
$this->assertArrayHasKey( 'action', $def['parameters']['properties'] );

Tests pin the canonical envelope — no test updates needed either.

Conclusion

Scope 2 of this issue can be checked off without a PR. The remaining work is scopes 1 (inc/Api/Chat/Tools/) and 3 (inc/Core/Steps/Publish/Handlers/), where the legacy property-keyed shape is still present (verified by spot-checking inc/Api/Chat/Tools/ListFlows.php, which still has 'required' => false per property).

[chubes4]

Resolved by:

• fix(publish-handlers): canonical JSON Schema for wordpress_publish and email_publish #1922 — fix(publish-handlers): canonical JSON Schema for wordpress_publish and email_publish (handler-tools scope)
• fix(chat-tools): canonical JSON Schema across inc/Api/Chat/Tools/ #1923 — fix(chat-tools): canonical JSON Schema across inc/Api/Chat/Tools/ (chat-tools scope)

Global tools scope (inc/Engine/AI/Tools/Global/) turned out to be a no-op — investigation confirmed those files were already converted as part of #1900 itself. The legacy required: true|false flags remaining in those files are settings/admin-UI form field defs, not AI tool schemas. Existing tests in BingWebmasterTest and ImageGenerationTest already assert the canonical shape.

Closing this tracking issue. Both real conversions landed.

Follow-up worth filing separately: DM still has two internal normalizers (ProviderRequestAssembler::normalizeToolParameters and RequestBuilder::normalizeToolSchema — the latter already gutted in #1900 to passthrough). With every tool now emitting canonical natively, the ProviderRequestAssembler legacy-bag branch is dead code and can be deleted on a future cleanup pass.