Problem
conversation-loop.php normalizes the Agents API conversation result, then adds Data Machine-specific fields directly at the top level.
Code reference on origin/main (008878b6):
inc/Engine/AI/conversation-loop.php:300-342 — adds completed, last_tool_calls, runtime_tool_pending, runtime_tool_pending_requests, completion assertion fields, max_turns_reached, and warning on the top-level result.
Related closed result-shape/context issues include #1514, #1569, #1667, and #2020.
Why this matters
Some of these fields are useful diagnostics, but the contract mixes canonical Agents API result fields with Data Machine runtime/provenance fields. For 1.0, callers should not need to know which top-level keys are substrate contract and which are product/runtime adornments.
Acceptance criteria
- Define the canonical Data Machine conversation result boundary for 1.0.
- Keep Agents API result fields canonical at top level, or explicitly document Data Machine's wrapper contract.
- Move Data Machine-only diagnostics into a namespaced key such as
runtime_provenance, metadata.datamachine, or another agreed container.
- Preserve required chat/UI behavior without relying on legacy aliases like
max_turns_reached unless intentionally retained.
- Tests cover budget exceeded, runtime tool pending, completion assertions, and chat response shaping.
AI assistance
- AI assistance: Yes
- Tool(s): OpenCode (GPT-5.5)
- Used for: 1.0 technical-debt audit and issue drafting; Chris requested tracking issues for the findings.
Problem
conversation-loop.phpnormalizes the Agents API conversation result, then adds Data Machine-specific fields directly at the top level.Code reference on
origin/main(008878b6):inc/Engine/AI/conversation-loop.php:300-342— addscompleted,last_tool_calls,runtime_tool_pending,runtime_tool_pending_requests, completion assertion fields,max_turns_reached, andwarningon the top-level result.Related closed result-shape/context issues include #1514, #1569, #1667, and #2020.
Why this matters
Some of these fields are useful diagnostics, but the contract mixes canonical Agents API result fields with Data Machine runtime/provenance fields. For 1.0, callers should not need to know which top-level keys are substrate contract and which are product/runtime adornments.
Acceptance criteria
runtime_provenance,metadata.datamachine, or another agreed container.max_turns_reachedunless intentionally retained.AI assistance