Skip to content

Normalize conversation-loop result shape at the Agents API boundary #2220

@chubes4

Description

@chubes4

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    1.0-blockerBlocks the Data Machine core 1.0 releasearchitectureFoundational architecture changes

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions