WP_Agent_Runtime_Overrides: persona-style per-agent overrides on WP_Agent

[lezama]

Problem

WP_Agent declares first-class agent identity (id, label, capability ceiling, conversation compaction policy, subagents). Consumers building "custom agents" — UI-defined personas where each row has its own system prompt, model, temperature, tool tier — reinvent the same value-object shape every time. Today there is no canonical place to put per-agent runtime overrides that the loop and providers will respect.

Proposal

New value object WP_Agent_Runtime_Overrides exposed on WP_Agent:

class WP_Agent_Runtime_Overrides {
    public function system_prompt(): ?string;
    public function provider_id(): ?string;
    public function model_id(): ?string;
    public function temperature(): ?float;
    public function max_iterations(): ?int;
    public function tier_1_tools(): array;   // composes with tool-discovery tier resolver
    public function greeting(): ?string;
}

class WP_Agent {
    // existing...
    public function runtime_overrides(): WP_Agent_Runtime_Overrides;
}

All fields are nullable — overrides only take effect when set. Loop reads them when building the conversation request; providers consume provider_id / model_id / temperature via wp-ai-client.

Composition

• Natural extension of how supports_conversation_compaction and conversation_compaction_policy are already declared on WP_Agent.
• tier_1_tools composes with the tiered tool resolver (separate issue).
• max_iterations slots into the existing WP_Agent_Iteration_Budget turns field.

Boundary

Storage is consumer-owned. Substrate defines the shape; concrete agent definitions (DB rows, JSON files, code-registered) materialize it.

Acceptance

• src/Registry/class-wp-agent-runtime-overrides.php
• WP_Agent::runtime_overrides() returns a normalized instance (empty by default)
• Loop honors max_iterations override (clamped against iteration budget)
• Conversation request carries provider_id / model_id / temperature into the runner
• Smoke: override round-trip, null-field passthrough, max_iterations clamp