Add a safely managed customer-support agent profile #2321

Objective

Add a managed customer-support agent profile that trusted integrations can provision idempotently and execute through the versioned customer-agent runtime from #2320, with a customer-specific prompt pipeline and immutable safety boundaries.

This must make the selected support agent's instructions authoritative without allowing the customer browser or consuming plugin to widen tools, collections, or privileges.

Pre-flight evidence

• includes/Models/Agent.php:1-18 defines custom agents with prompts, models, Tier-1 tools, greetings, and iteration settings.
• includes/Models/Agent.php:349-394 maps a selected agent's prompt to agent_system_prompt and applies model/tool overrides.
• includes/Core/AgentLoop.php:358-369 can use agent_system_prompt, but includes/Core/AgentLoop.php:462-468 locks any explicit system_instruction instead.
• includes/REST/SessionController.php:1850-1865 passes both agent_id and a hard-coded public system_instruction; the locked instruction therefore bypasses the selected agent prompt.
• includes/REST/SessionController.php:1951-1966 contains the current fixed documentation-assistant prompt.
• includes/Core/SystemInstructionBuilder.php:108-128 appends global advanced-companion, memory, and skill context, which must not leak into a customer support profile.
• includes/Abilities/PublicChatSetupAbilities.php:27-28 correctly constrains the existing public setup path to sd-ai-agent/knowledge-search only.
• Closed Add anonymous customer mode with safe tool allowlist #2176 implemented anonymous-safe gating, while closed Set up Ultimate Multisite public docs assistant #2190 was a production docs-assistant setup task; neither provides a reusable managed support-profile lifecycle.

Scope

Managed profile lifecycle

• Extend the Expose a versioned server-side customer-agent runtime #2320 runtime with an idempotent ensure_profile/status operation keyed by a stable integration key such as ultimate-multisite-support-tickets and a profile/spec version.
• Reuse the existing agent model where appropriate, but add explicit managed ownership metadata rather than guessing ownership from an agent name or numeric ID.
• Define per-field ownership:
  • integration-managed safety envelope, allowed ability set, allowed knowledge collections, profile schema version, and customer mode cannot be widened in the normal agent editor;
  • operator-managed provider/model, greeting/avatar/brand copy, approved collections, and bounded generation settings survive repeated provisioning unless the operator requests reset;
  • document any fields intentionally reset when the integration's safety spec version increases.
• Return a customer-safe health summary: profile key/version, enabled/ready state, missing provider/model/collection reasons, safe capability list, and drift status. Never return raw prompts, credentials, or private collection contents to the consumer.
• Support disable, re-provision, and remove semantics without deleting unrelated custom agents or conversations.

Customer-specific prompt policy

• Introduce an explicit prompt composition path for customer agents. Required precedence:
  1. immutable Superdav customer-safety envelope;
  2. managed profile/support instructions;
  3. approved knowledge/citation guidance;
  4. bounded, sanitized request context from the trusted consumer.
• Do not use the current locked hard-coded prompt in a way that discards the profile prompt.
• Do not inherit global site-agent memories, skill indexes, advanced-companion instructions, admin page context, or normal authenticated agent defaults.
• The default support profile should:
  • identify itself as an AI support assistant;
  • answer from approved Ultimate Multisite documentation/knowledge and cite source titles/URLs when present;
  • say when evidence is insufficient rather than inventing an answer;
  • invite/escalate to a human through a structured handoff signal rather than claiming a person has been contacted;
  • never claim access to private account/site data, billing, licenses, admin, files, database, users, settings, WP-CLI, memory, or internal REST tools.
• Return structured handoff intent/reason separately from display text when the model requests a human, detects account/private-data needs, or cannot answer safely.

Tool and knowledge policy

• Default to sd-ai-agent/knowledge-search only. Reject meta-tools, client/browser tools, attachments, mutations, memory, skills, internal REST dispatch, and generic CLI/file/database abilities.
• Compute effective abilities and collections as the intersection of Superdav's immutable customer-safe set, the managed profile policy, and current operator-approved resources. A consumer request can narrow this set but never widen it.
• Validate referenced collections exist and are public/customer-approved before marking the profile ready.
• Keep public anonymous-chat behavior backward compatible; migrate it to the shared prompt/profile primitives only when tests prove no behavior regression.

Acceptance criteria

• Provisioning the same integration/profile spec repeatedly yields one managed profile and preserves documented operator-owned fields.
• A safety-spec upgrade updates only managed fields and reports drift/reset actions.
• The executed system instruction contains the safety envelope and selected support instructions, but no global memory, skill index, advanced-companion, or admin instructions.
• Attempts to add a privileged tool/collection through consumer input or the generic agent editor fail closed.
• A missing/disabled provider, model, or collection produces a precise non-secret readiness error.
• Runtime results can include a normalized handoff signal without relying on phrase matching in generated prose.
• Existing custom agents and /public-chat/* flows continue to work.

Reference pattern

Follow Agent model CRUD/DTO conventions and PublicChatSetupAbilities fail-closed knowledge policy, while adding explicit managed-field ownership and a customer-only prompt composer instead of overloading the global prompt builder.

Files to modify

• includes/Models/Agent.php and includes/Models/DTO/AgentRow.php — existing agent configuration and persistence.
• includes/Core/AgentLoop.php — current prompt override precedence and anonymous gates.
• includes/Core/SystemInstructionBuilder.php — reference only; customer mode must not append private/global context.
• includes/REST/SessionController.php — replace the hard-coded selected-agent bypass with shared customer prompt primitives where appropriate.
• includes/Abilities/PublicChatSetupAbilities.php — safe knowledge-only setup reference.
• includes/Tools/ToolDiscovery.php and includes/Abilities/KnowledgeAbilities.php — effective policy enforcement.
• Add focused managed-profile and customer-prompt tests under tests/SdAiAgent/Models/, tests/SdAiAgent/Core/, and/or tests/SdAiAgent/Services/.

Verification

• Run the new managed-profile lifecycle and prompt-composition tests.
• Run vendor/bin/phpunit --filter 'AgentTest|AgentLoopTest|SystemInstructionBuilderTest|PublicChatControllerTest|PublicChatSetupAbilitiesTest|ToolDiscoveryTest|KnowledgeAbilitiesTest'.
• Run the repository PHPStan and PHPCS commands and the full PHP test suite.

Dependencies and delivery notes

• Blocked by Expose a versioned server-side customer-agent runtime #2320; implement against its final contract rather than introducing a second integration API.
• This is distinct from closed Set up Ultimate Multisite public docs assistant #2190: that issue configured one production docs embed, while this issue provides a reusable, versioned, safely managed support profile.
• Target workload: tier:thinking, high priority, approximately 4 hours.

CI Repair Feedback (from PR #2324)

The previous worker's PR #2324 had terminal failed CI checks. The PR has been
closed and this issue re-queued for dispatch. The next worker should address these failures.

Terminal failed checks

• PHPUnit: failure — check URL
• Static Analysis (PHPCS + PHPStan): failure — check URL

Worker guidance

1. Recover the previous PR branch/commits and continue that work; do not restart from scratch.
2. Read every terminal check URL above and preserve the accumulated evidence.
3. Rebase the recovered work onto current origin/main, then fix the code rather than weakening CI.
4. Run every listed local check and create the replacement PR from the recovered branch.

Routed by deterministic merge pass (pulse-merge.sh).

In-place repair fallback

• Reason: the bounded PR-branch repair session exhausted its retry budget
• Retry: re-run the deterministic merge pass after restoring access to branch feature/auto-20260724-125342-gh2321; keep PR auto-recover: orphaned worker branch for #2321 #2324 open until that retry is impossible.