Document and extend the WP_Agent_Channel chat ability contract for bridge metadata

[chubes4]

Context

PR #99 added AgentsAPI\AI\Channels\WP_Agent_Channel, which gives direct webhook-style transports a reusable way to run a chat ability and deliver a response:

• Add WP_Agent_Channel base class for messaging transports #99

That PR already establishes the minimum chat ability call shape used by WP_Agent_Channel::run_agent():

$ability->execute(
    array(
        'agent'      => $this->agent_slug,
        'message'    => $message_text,
        'session_id' => '' === (string) $this->session_id ? null : $this->session_id,
    )
);

and WP_Agent_Channel::deliver_result() already understands these output shapes:

array(
    'reply'      => 'assistant text',
    'session_id' => 'optional-new-session-id',
)

or:

array(
    'messages' => array(
        array( 'role' => 'assistant', 'content' => 'assistant text' ),
    ),
)

The first consumer is Miguel's openclaWP wacli transport:

• Add WhatsApp transport via openclaw/wacli + wp-admin pairing UI lezama/openclawp#6

Data Machine has a parallel bridge entry point through datamachine/send-message in data-machine-chat-bridge:

• https://github.com/Extra-Chill/data-machine-chat-bridge

These systems overlap around the same primitive: send one user message to one WP agent, optionally continue a session, and return assistant output.

Problem

The minimum contract exists, but it is not yet documented as a durable Agents API contract, and it does not yet describe the richer metadata that real channels and remote bridges need:

• attachments
• source/client context
• external provider/channel identity
• external conversation/thread ID
• external message ID for idempotency
• room kind (dm, group, channel)
• optional runtime metadata/tool/turn information

Without documenting the base contract and defining its bridge-ready extension points, each runtime will keep growing incompatible variants (openclawp/chat, datamachine/send-message, future Intelligence chat ability, etc.).

Current shapes

openclawp/chat aligns with the minimum WP_Agent_Channel contract:

{
  "agent": "agent-slug",
  "message": "text",
  "session_id": "optional"
}

and returns:

{
  "session_id": "uuid",
  "reply": "assistant text",
  "completed": true
}

datamachine/send-message accepts a richer shape:

{
  "message": "text",
  "agent_id": 123,
  "session_id": "optional",
  "attachments": [],
  "client_context": {}
}

and returns Data Machine's chat response shape (session_id, response, completed, metadata/tool data, etc.).

Proposal

Document the existing minimum WP_Agent_Channel chat ability contract, then extend it in a backward-compatible way for bridge/channel metadata.

Base input, already used by WP_Agent_Channel:

{
  "agent": "agent-slug",
  "message": "text",
  "session_id": "optional"
}

Bridge-ready input extension:

{
  "agent": "agent-slug-or-id",
  "message": "text",
  "session_id": "optional",
  "attachments": [],
  "client_context": {
    "source": "channel|bridge|rest|block",
    "client_name": "wacli",
    "external_provider": "whatsapp",
    "external_conversation_id": "opaque-room-id",
    "external_message_id": "opaque-message-id",
    "room_kind": "dm|group|channel"
  }
}

Base output, already understood by WP_Agent_Channel:

{
  "session_id": "uuid",
  "reply": "assistant text",
  "completed": true
}

Optional richer output:

{
  "session_id": "uuid",
  "reply": "assistant text",
  "messages": [],
  "completed": true,
  "metadata": {}
}

Acceptance criteria

• Document the existing WP_Agent_Channel chat ability input/output contract as the minimum portable contract.
• Document optional bridge/channel fields (attachments, client_context) without breaking existing ability implementations.
• Decide whether WP_Agent_Channel::run_agent() should pass normalized client_context once issue Add normalized channel message and session mapping primitives #102 lands.
• Decide whether extract_replies() should also understand response as a common alias for reply, since Data Machine uses that field today.
• Leave runtimes free to register adapters behind the contract (openclawp/chat, Data Machine, Intelligence, etc.).

Why this belongs in agents-api

The overlap is now visible in at least two implementations. A documented contract makes WP_Agent_Channel and future remote bridge APIs portable without forcing every channel or bridge to hard-code runtime-specific ability shapes.

Related issues:

• Extract generic remote chat bridge registration, queue, pending, and ack primitives #101
• Add normalized channel message and session mapping primitives #102
• Add generic webhook verification and inbound idempotency helpers for channels #103
• Design generic bridge authorization and onboarding flow for external clients #104

[lezama]

PR #105 implements the agents-api side of this:

• WP_Agent_Channel::run_agent() now dispatches the canonical input shape (agent / message / session_id / attachments / client_context with source / client_name / external_provider / external_conversation_id / external_message_id / room_kind).
• 4 new overridable hooks back the richer fields, all with sensible defaults so existing concrete channels keep working without changes.
• build_chat_payload() is public so subclasses, bridges, and tests can introspect or extend the shape.
• Backwards compatible: openclawp/chat still works as-is (extra keys ignored).

lezama/openclawp PR #6 already overrides the new hooks for the WhatsApp case (msg_id → external_message_id, JID suffix → room_kind), so we have a working concrete consumer that exercises the contract.

Open question I'd love your take on @chubes4: should we also ship a no-op agents-api/canonical-chat-contract ability (shape-checked input/output, dispatches to whichever runtime is registered as the resolver) so plugins get a single, stable target instead of relying on the wp_agent_channel_chat_ability filter to point at openclawp/chat vs datamachine/send-message? That's a follow-up, but worth knowing if you want it now or later.

[chubes4]

I don't think the canonical chat contract makes sense as an ability. I think the consumers should be refactored to wrap the Agents API abilities, instead of using the agents API as a router

[lezama]

Here's how I'd draw the boundary going forward.

In agents-api

• The canonical chat contract: agent, message, session_id, attachments, client_context.
• WP_Agent_Channel.
• Eventually a stable ability like agents-api/chat or agents-api/canonical-chat — but as a contract/resolver, not a UI.

In openclawp

The simple chat as a usable product/demo:

• blocks/chat/
• OpenclaWP_Admin (wp-admin → Chat)
• OpenclaWP_Rest
• OpenclaWP_Runner
• openclawp/chat ability, for now.

The rule

agents-api shouldn't ship a chat experience yet. It should ship primitives. The simple chat in openclawp is the first real consumer and the proof the primitives are useful.

What moves up to agents-api over time

• The chat input/output shape (Canonical chat contract: WP_Agent_Channel + agents/chat ability (#100) #105 covers this)
• Session continuity expectations
• The client_context schema
• Maybe a stable ability resolver

What stays in openclawp

• blocks/chat
• wp-admin → Chat
• OpenclaWP_Runner
• Tool-resolver-specific behavior
• Provider fallback / error copy

That stays in openclawp because it has a product opinion: "a WP site where you chat with a registered agent." No reason to drag that into a primitive substrate.

Resulting architecture

agents-api      registry, conversation loop, tool contracts,
                channel base, canonical chat contract

openclawp       simple chat product + wp-admin UI + REST + runner

wacli/WhatsApp  channel adapter targeting the canonical chat contract

So openclawp isn't "something to move" — it's the reference consumer. When Data Machine, Dolly, WhatsApp Cloud API, and wacli all need the same piece, that piece moves up to agents-api. Everything else stays.

[lezama]

Done — landed agents/chat in PR #105 (second commit).

• Stable slug: agents/chat
• Filter for runtime registration: wp_agent_chat_handler (first-hook-wins; helper AgentsAPI\AI\Channels\register_chat_handler( $callable ) for readability)
• Permission gate: manage_options default, filterable via agents_chat_permission for surfaces with their own auth (HMAC webhooks, OAuth, etc.)
• WP_Agent_Channel::run_agent() default flipped from openclawp/chat to agents/chat — channels target the canonical slug out of the box, the wp_agent_channel_chat_ability filter remains the escape hatch
• Input/output JSON schemas embedded in the ability registration

lezama/openclawp#6 is updated alongside: openclawp registers itself as the agents/chat runtime, keeping openclawp/chat for backwards compat. So the wacli channel now flows: webhook → WP_Agent_Channel → agents/chat → openclaWP's runner.

@chubes4 — when Data Machine wants to register, it's a one-liner via add_filter( 'wp_agent_chat_handler', … ) or the helper. Happy to draft a Data-Machine-side adapter if that's helpful, but it's literally:

AgentsAPI\AI\Channels\register_chat_handler( [ DM_Chat_Adapter::class, 'execute' ] );

where the adapter unpacks the canonical input and calls into Data Machine's existing send-message flow.