Normalize AI tool result packet contracts

[chubes4]

Summary

• Adds a ToolExecutionResult helper to normalize tool execution result entries and payload envelopes before AI step packet emission.
• Emits explicit packet metadata for tool_result_envelope, tool_result_data, tool_result_shape, and tool_result_contract while preserving legacy tool_result compatibility.
• Updates ToolResultFinder to read canonical envelopes and legacy packets consistently when matching successful handler results.

Refs #2262.

Tests

• php tests/upsert-handler-result-handoff-smoke.php
• php tests/ai-completion-assertion-packet-smoke.php
• php tests/agent-conversation-result-smoke.php
• php tests/ability-result-wp-error-smoke.php
• vendor/bin/phpcs inc/Engine/AI/Tools/ToolExecutionResult.php inc/Engine/AI/Tools/ToolResultFinder.php inc/Core/Steps/AI/AIStep.php tests/Unit/Engine/AI/Tools/ToolResultFinderTest.php tests/Unit/Core/Steps/AI/AIStepTest.php tests/upsert-handler-result-handoff-smoke.php tests/ai-completion-assertion-packet-smoke.php
• php -l inc/Engine/AI/Tools/ToolExecutionResult.php
• php -l inc/Engine/AI/Tools/ToolResultFinder.php
• php -l inc/Core/Steps/AI/AIStep.php

Not run:

• vendor/bin/phpunit ... because this checkout does not install phpunit.
• homeboy test --path /Users/chubes/Developer/data-machine@fix-tool-execution-result-contract --extension wordpress --filter ToolResultFinder because Homeboy auto-selected lab runner lab, which is missing PHP and Composer.

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Drafted the implementation, tests, verification commands, and PR description for Chris to review.

[homeboy-ci]

Homeboy Results — data-machine

Lint

❌ lint — failed

• formatting — 2 finding(s)
• Total: 2 finding(s)

ℹ️ Auto-fix: homeboy lint data-machine --path /home/runner/work/data-machine/data-machine --changed-since 0a1cd54 --fix (or homeboy refactor data-machine --path /home/runner/work/data-machine/data-machine --changed-since 0a1cd54 --from lint --write)
ℹ️ Some issues may require manual fixes
ℹ️ Full options: homeboy docs commands/lint
Deep dive: homeboy lint data-machine --changed-since 0a1cd54

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-data-machine-lint-quality-Linux-node24 contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-data-machine-lint-quality-Linux-node24 contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/data-machine/actions/runs/26451446288

Test

❌ test — failed

• 2 failed out of 1014 total
• 3 skipped

ℹ️ To run specific tests: homeboy test data-machine -- --filter=TestName
ℹ️ Auto-fix lint issues: homeboy refactor data-machine --from lint --write
ℹ️ Collect coverage: homeboy test data-machine --coverage
ℹ️ Save test baseline: homeboy test data-machine --baseline
ℹ️ Analyze failures: homeboy test data-machine --analyze
ℹ️ Pass args to test runner: homeboy test -- [args]
ℹ️ Full options: homeboy docs commands/test
Deep dive: homeboy test data-machine --changed-since 0a1cd54

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-data-machine-test-quality-Linux-node24 contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-data-machine-test-quality-Linux-node24 contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/data-machine/actions/runs/26451446288

Audit

✅ audit — passed

• dead_code — 146 finding(s)
• requested_detectors — 123 finding(s)
• intra-method-duplication — 64 finding(s)
• repeated_literal_shape — 13 finding(s)
• field_patterns — 9 finding(s)
• Taxonomy — 5 finding(s)
• Abilities — 4 finding(s)
• Flow — 4 finding(s)
• structural — 4 finding(s)
• File — 2 finding(s)
• Total: 386 finding(s)

Deep dive: homeboy audit data-machine --changed-since 0a1cd54

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-data-machine-audit-quality-Linux-node24 contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-data-machine-audit-quality-Linux-node24 contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/data-machine/actions/runs/26451446288

Tooling versions

• Homeboy CLI: homeboy 0.198.9+d7b015ed
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: bbe282b9
• Action: unknown@unknown

[chubes4]

Closing to avoid an overlapping competing implementation with #2267. PR #2267 already owns the practical tool-result/handler packet contract fix across AIStep, ToolResultFinder, Publish/Upsert projection, and scalar result normalization. Recommendation for #2262: treat it as covered by #2267 after the blocking success/data projection review finding is fixed; if a separate canonical ToolExecutionResult seam is still desired, it should be opened later as a narrow follow-up based on #2267 rather than parallel to it.