AI Agents as synthetic users with user-meta storage

01Summary

Implement OpenStation Agents: durable, addressable workers that live on the site as real WordPress users, take orders by chat, send-to, drag, hook, or HTTP, and act through the WordPress Abilities API under the agent's own role and capabilities. The objectives, trigger model, tools model, security posture, and build order come from PR #240.

02Problem frame

PR #240 (WordPress/openstation#240, branch origin/my-agents) shipped a UX mock plus an architecture manifesto, and the branch actually carries a near-complete implementation (~12k lines: identity, behaviour, bindings, abilities bridge, runner, REST, My WordPress UI, run window, send-to dispatcher, six PHPUnit suites, three vitest suites). Two reasons we cannot merge or rebase it as-is:

03Requirements

Extracted from PR #240's body. Markers: kept unchanged, adapted same objective with a trunk-reality or storage change, dropped consciously not carried over.

Identity (Layer 1) kept

• R1. Each agent is a real wp_users row with a standard WP role (administrator, editor, author, contributor). Capability checks are real WP checks; a tool call the agent's role cannot perform fails the same way it would for a human.
• R2. Login is fully blocked: the authenticate filter rejects agents, password resets are disabled, cookie/REST auth refuses them, application passwords cannot be created for them, no email is ever sent to them (synthetic reserved address).
• R3. Identity surface works end to end: avatar, display name, attribution on revisions, comments, _edit_lock, and audit trails show the agent as the actor.

Definition (was Layers 2+3) adapted: all user meta

• R4. The agent's behaviour (system prompt, "when to use" description, ability allowlist) is editable from the OpenStation UI. Adapted: stored as user meta on the agent's row, not as a wp_guideline post.
• R5. Site-specific bindings (trigger configuration, per-agent model override, per-agent rate limit) are user meta on the agent's row. This part already matched the PR (its Layer 3).
• R6. dropped Push MD / Claude Code / Codex ecosystem portability via wp_guideline (skills/{slug}/SKILL.md materialisation), and skills-as-attachable-child-guidelines. With user-meta storage there is no CPT for those tools to consume. If portability returns later it will be an explicit export surface, not the storage layer.

Triggers kept

• R7. Five trigger kinds, one engine: chat (double-click the agent, conversation window), drag & drop (drop a tile onto the agent), hook (subscribe to a WP action such as save_post / wp_insert_comment), REST endpoint (authenticated POST to a per-agent route), agent-to-agent (one agent's output feeds another). The branch added a sixth that we keep because it shipped as the mock's first working surface: send-to (agent appears in the right-click "Send to…" menu for chosen entity kinds).
• R8. All triggers collapse to the same loop: a message arrives, the agent's system prompt + message become an LLM call, the model picks tools off the allowlist, tools run as the agent's user, the result is the trigger's return value. Drag is chat with a payload; a hook is chat where the message is the hook args; an endpoint is chat where the body is the message.
• R9. Trigger configuration carries its own auth (capability for chat, REST permission for endpoints, the firing context for hooks). The agent never runs un-gated.

Tools adapted to trunk

• R10. Tools are the WordPress Abilities API: the picker is a view over wp_get_abilities(), each pick is stored on the agent (allowlist meta), each call is dispatched through WP_Ability::execute() so the ability's own permission_callback and schemas gate it. Any plugin that registers an ability becomes agent-compatible with zero bespoke integration. Adapted: the PR's fallback registry openstation_register_ai_tool() no longer exists; abilities are the only tool source.
• R11. Selecting a tool never elevates: capabilities are inherited from the agent's role, not granted by the picker.

LLM adapted to trunk

• R12. Bring-your-own model via WP Core Connectors + AI Client (trunk reality; the PR predates the removal of openstation_register_ai_provider). No connector configured: "Create agent" is disabled with a notice linking options-connectors.php; existing agents remain visible for audit. Availability check is the existing openstation_ai_is_available() / openstation_ai_provider_configured() pair.
• R13. Per-agent model override is a binding (user meta), passed to the AI Client per call when set.

Security kept

• R14. Agents are users: every action lands in the existing audit trail with the agent's user ID as actor. No parallel ACL.
• R15. Tool results are sanitised before re-entering the LLM context; no outbound credentials in payloads.
• R16. Behaviour changes are auditable. Adapted: user meta has no revisions (this is the real cost of leaving wp_guideline). Mitigation in D6 below.

Surface and rollout kept

• R17. UI home is an "Agents" section in the My WordPress window: list on the left, Define / Tools / Triggers panes on the right, "+ Create agent" flow.
• R18. Everything ships behind a feature flag until the contract settles.
• R19. deferred Marketplace (packaged agent definitions shipped by third parties) is out of scope for this plan; noted as future work.

04Scope boundaries

• No wp_guideline reads or writes anywhere in the module. No Gutenberg or Guidelines-experiment dependency, no gutenberg-gate.php port, no read_guidelines capability shims.
• No Push MD export in v1 (candidate follow-up: a read-only exporter that projects agent meta into SKILL.md shape).
• No skills entity in v1. The system prompt is the behaviour. If reusable snippets are wanted later they can become an additional meta key or the export surface above.
• No streaming in the chat window v1 (the invoke REST route is request/response; the existing admin-ajax SSE pattern from AI Copilot is the follow-up path).
• No anonymous REST-endpoint trigger in v1; endpoint auth is capability or application-password based. Anonymous mode with rate limits is a follow-up.
• No conversation-history persistence in v1 (the PR's "history per user × agent"); the chat window keeps history in a shared store for the session. Persistence is a follow-up decision (likely user meta on the human, not the agent).
• No marketplace.
• WordPress < 7.0 (no Abilities API / AI Client): the module loads its storage + UI but the runner and invoke routes return the same unavailability the AI Copilot does; creation is gated exactly like R12.

Deferred to follow-up work

05Context & research

Trunk surfaces this builds on (verified on 0.9.7)

Prior art: branch origin/my-agents (fork point 0.8.8)

Port targets, in decreasing reusability:

Implementation gotchas surfaced by research

• The AI Copilot advertises only readonly-annotated abilities to its assistant (prompt-injection posture, includes/ai-copilot/abilities.php:66). Agents deliberately differ: mutating abilities are the point ("an agent that does things"). The compensating controls are the explicit per-agent allowlist set by a privileged human, the agent's role, and each ability's own permission_callback (D4).
• wp_insert_user requires an email; the branch's synthetic reserved-address helper exists precisely to satisfy schema validation while guaranteeing nothing is ever delivered. Keep it, and keep email_exists() uniqueness.
• Role assignment on create must respect get_editable_roles() for the acting user, or a lower-privileged user could mint an administrator agent (WP's own promote semantics).
• The runner switches identity (wp_set_current_user) so ability permission callbacks see the agent. The switch must be wrapped so the original user is restored on every path including exceptions, and nothing else in the request (nonce checks already done, response rendering) runs as the agent.
• Hook triggers must not run the LLM synchronously inside save_post (blocks the editor save round-trip). Reuse the AI Copilot's cron single-event + transient dedup pattern.
• Agents appear in wp/v2/users and the Users window like any user. They need a visible badge and a way to exclude them from "real people" flows (bulk password reset, welcome emails) without hiding them from audit.

06Key technical decisions

D1. Storage model: one user, one meta namespace

All agent data hangs off the agent's wp_users row:

Name = display_name; slug = user_login minus the agent- prefix; avatar = the user's avatar. Single-value meta, JSON-encoded arrays (one row each) so a read is one get_user_meta call and the shape round-trips through REST cleanly. All keys registered via register_meta( 'user', … ) with sanitize callbacks, show_in_rest => false (the module's own REST surface is the only reader/writer; core wp/v2/users never exposes them).

07Open questions

08High-level technical design

Storage: the whole agent hangs off one user row

wp_users row (role, display_name, user_login 'agent-<slug>', avatar)
  └── user meta                            ← the whole agent definition
      _desktop_mode_agent                = '1'
      _desktop_mode_agent_description    ┐
      _desktop_mode_agent_instructions   ├ behaviour  (was wp_guideline)
      _desktop_mode_agent_abilities      ┘
      _desktop_mode_agent_triggers       ┐
      _desktop_mode_agent_model          ├ bindings   (unchanged from PR)
      _desktop_mode_agent_rate_limit     ┘

Trigger intakes → engine → effects

flowchart LR
  subgraph IN["Trigger intakes"]
    direction TB
    C["chat window"]:::in
    S["send-to menu"]:::in
    D["drag drop"]:::in
    H["hook subscription"]:::in
    E["endpoint route"]:::in
    A["agent-to-agent"]:::in
  end
  subgraph ENG["Engine"]
    R["POST /desktop-mode/v1/agents/{id}/invoke
openstation_agent_invoke()
switch to agent user ·
prompt+message → wp_ai_client_prompt ·
tool loop ≤ 8 turns · restore user"]:::eng
  end
  subgraph FX["Effects"]
    direction TB
    X["WP_Ability::execute()
as the agent user"]:::fx
    K["openstation_agent_completed
feeds chaining + run window"]:::fx
  end
  C --> R
  S --> R
  D --> R
  H --> R
  E --> R
  A --> R
  R --> X
  R --> K
  classDef in fill:#f3effe,stroke:#c0adfb,color:#46329b;
  classDef eng fill:#eef4ff,stroke:#9bb8f0,color:#1c3a6e;
  classDef fx fill:#eafaf8,stroke:#7fd8cf,color:#0a6b62;
      

Module layout

Mirrors the branch minus the guideline files:

includes/agents/            src/
  bootstrap.php               my-wordpress/agents-renderer.ts   (kind renderer + panes)
  identity.php                my-wordpress/agents-rest.ts       (client for /agents)
  store.php     (meta CRUD)   my-wordpress/agents-types.ts
  abilities.php (catalogue)   my-wordpress/agents-abilities.ts  (picker)
  runner.php                  my-wordpress/agents-triggers-ui.ts
  rest.php                    agents-send-to.ts                 (send-to + drop targets)
  triggers.php  (hook/endpoint wiring)
  run-window.php              agent-run-window.ts               (chat/run window bundle)
  privacy.php

09Implementation units

10System-wide impact

• Users surfaces: agents appear in wp/v2/users, the Users window, and author dropdowns. U1 ships the wp-admin column; U4 adds the OpenStation badge via the existing users-window register_rest_field enrichment. Bulk actions that email users (password reset, welcome) must skip agents (guard in the existing bulk routes).
• Presence: agents never heartbeat, so they read as offline; no change needed, but the badge should prevent "why is this user always offline" confusion.
• Payload: no changes to openstation_build_menu_payload() in v1 (Agents lives inside My WordPress + its own window registration, both already carried). A future per-agent desktop tile would ride openstation_icons.
• AI Copilot: untouched. The runner reuses client.php helpers but registers nothing on the copilot's hook surface. A follow-up could expose agents to the copilot as commands.
• Uninstall/cleanup: deleting the plugin must decide what happens to agent users (default: leave them, they are inert without the module; document it). Deactivating the flag hides surfaces but keeps data.

11Risk analysis & mitigation

12Phased delivery

13Documentation plan

• docs/hooks-reference.md: openstation_agent_{created,updated,deleted,completed} actions; openstation_agent_trigger_kinds, openstation_agent_allowed_abilities, openstation_agent_hook_catalogue, permission filters.
• docs/javascript-reference.md: agents REST client surface, run-window shared-store key, send-to integration points.
• docs/api-index.md + includes/rest/README.md: new PHP functions and REST routes.
• docs/architecture.md: the two-layer agent model (user row + meta), runner flow, trigger engine.
• docs/examples/agents.md: rewrite of the branch's example for the meta-backed API (register a trigger kind, invoke an agent programmatically), indexed in docs/examples/README.md.
• Migration note: none needed (new surface, flag off), but the audit trade-off (D6) and the least-privilege role recommendation go in the example and architecture docs.

14Sources & references

• PR #240 body (objectives, three-layer model, five triggers, abilities-as-tools, security posture, build order): github.com/WordPress/openstation/pull/240
• Branch origin/my-agents (commits 6b598c80, c3e3b1a5, 13f830f5): prior implementation used as reference, fork point 0.8.8.
• Trunk AI substrate: includes/ai-copilot/{client,settings,abilities,search}.php, docs/migration-ai-connectors.md (removal of provider registry + tool registry in 0.9.4).
• Extension seams: includes/registries/native-windows.php, includes/my-wordpress/window.php, src/my-wordpress/kind-registry.ts, src/drag/, includes/extended-options.php, includes/games/bootstrap.php (flag pattern), includes/ai-copilot/{jobs,hooks}.php (async pattern).