Define host-owned tool declarations for conversation requests

[chubes4]

Problem

WP_Agent_Conversation_Request carries a tools field, but the current normalizer routes every entry through WP_Agent_Tool_Declaration::normalize().

That declaration contract is intentionally narrow for run-scoped client tools:

• names must be client/<tool>
• source must resolve to client
• executor must be client
• scope must be run

That leaves no canonical way for a host runtime such as Data Machine to include its actual model-facing server/host tools in the request envelope. Data Machine currently constructs the Agents API request with an empty tools array while separately sending real tools through its provider request builder.

Current evidence

• src/Runtime/class-wp-agent-conversation-request.php normalizes request tools through WP_Agent_Tool_Declaration::normalize().
• src/Tools/class-wp-agent-tool-declaration.php only accepts client/run-scoped declarations.
• Extra-Chill/data-machine builds WP_Agent_Conversation_Request with array() for tools in inc/Engine/AI/conversation-loop.php, even when real model-facing tools are available.

Why this matters

The request contract is supposed to be the replay/audit surface for a conversation run. If actual host/server tools are absent from WP_Agent_Conversation_Request, transcript stores, replay consumers, debug UIs, and downstream orchestrators cannot reconstruct the model-facing tool catalog from the canonical Agents API request.

Desired contract

Agents API should represent both tool families without forcing product vocabulary into the substrate:

• client runtime tools: run-scoped, externally/client fulfilled, current client/* contract.
• host/server tools: host-owned declarations backed by abilities, product adapters, or other runtime executors.

Possible shapes:

• broaden WP_Agent_Tool_Declaration with explicit executor/scope variants, or
• add a separate host-tool declaration value object and let WP_Agent_Conversation_Request normalize both.

Acceptance criteria

• WP_Agent_Conversation_Request can carry the full model-facing tool catalog for a run, including host/server tools.
• Client runtime tools retain their strict client/*, executor=client, scope=run validation.
• Host/server declarations have generic required fields: stable name, description, parameters schema, source/executor metadata, and optional runtime metadata.
• The resulting request array remains storage-neutral and product-neutral.
• Data Machine can pass its resolved tools into the request without using array() or duplicating a side-channel.
• Tests cover valid client tools, valid host/server tools, invalid mixed declarations, and request to_array() replay shape.

Related

• Data Machine mediation migration: Migrate conversation tool execution to Agents API mediation Extra-Chill/data-machine#2453
• Provider-turn adapter contract: Define provider-turn adapter contract for conversation runtimes #268
• Mediated tool preflight/external pending hooks: Expose mediated tool preflight and external-tool pending hooks #259

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (openai/gpt-5.5)
• Used for: Boundary audit across Agents API, Data Machine, and Data Machine Code; drafted this tracker for Chris to review and prioritize.