Add canonical chat run lifecycle events

[chubes4]

Problem

Agents API already emits useful internal lifecycle events from WP_Agent_Conversation_Loop through the caller-owned on_event sink, including turn_started, tool_call, tool_result, approval_required, interrupt_received, budget_exceeded, completed, and failed.

The public chat run-control contract only exposes coarse run status through agents/get-chat-run (queued, running, cancelling, cancelled, completed, failed). Product UIs that want richer progress need to invent their own event plumbing instead of consuming a shared Agents API surface.

Studio Web hit this while improving its browser Playground loading/generation UX: it can animate optimistic phases locally, but exact agent/tool lifecycle progress should be reusable across Studio Web, frontend-agent-chat, wp-admin agents, Calypso, Kimaki, and other clients.

Proposed contract

Add a canonical, client-addressable chat run events surface, for example:

• persist bounded, ordered lifecycle events for a chat run
• expose those events through a canonical ability such as agents/list-chat-run-events, or by extending agents/get-chat-run with cursorable events
• support cursor-based incremental reads so polling clients can fetch only new events
• keep event payloads redacted/safe by default; tool names and tool call IDs are useful, raw tool parameters may need redaction or omission

Example shape:

{
  "run_id": "run_123",
  "session_id": "session_123",
  "status": "running",
  "events": [
    {
      "id": "evt_1",
      "type": "turn_started",
      "message": "Thinking...",
      "created_at": "2026-05-29T23:00:00Z",
      "metadata": { "turn": 1 }
    },
    {
      "id": "evt_2",
      "type": "tool_call",
      "message": "Calling studio_web_start_generation...",
      "created_at": "2026-05-29T23:00:01Z",
      "metadata": {
        "tool_name": "studio_web_start_generation",
        "tool_call_id": "call_123"
      }
    }
  ],
  "cursor": "evt_2"
}

Acceptance criteria

• Agents API persists canonical lifecycle events for addressable chat runs started through WP_Agent_Conversation_Loop.
• Events are ordered, cursor-addressable, and scoped by both session_id and run_id.
• A canonical ability exposes events to clients, either as a new run-events ability or as a compatible extension to agents/get-chat-run.
• Event payloads are safe for UI consumption and do not expose raw secret-bearing parameters.
• Existing run-control behavior remains compatible.
• Smoke coverage proves event persistence, cursor reads, session/run scoping, and redaction behavior.

Downstream usage

Studio Web can consume these lifecycle events through frontend-agent-chat and map them into preview animation phases inside the browser Playground starter theme, instead of inventing a product-specific general lifecycle surface.

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Drafting this issue from repository inspection and product discussion; Chris remains responsible for prioritization and review.

[chubes4]

Fixed upstream by #245. Downstream Studio Web / frontend-agent-chat integration is being handled in stacked work, so this Agents API tracking issue can close.