Specflux Site Agent

Description

Specflux Site Agent runs an agent loop on behalf of a logged-in user: one goal, many
model turns, many tool calls — pausing for a human whenever a write needs
approval, whenever the model needs to ask a clarifying question, or before
its first side-effecting write — and resuming exactly where it left off.

• Runs are session-bound. A run acts as the user who started it; nothing
  runs in the background.
• Tools are WordPress Abilities, restricted per run to an allow-list
  supplied directly by the consumer, or derived from a registered pack
  (a named tool surface — pages, posts, site, or commerce, all bundled).
• Two gate modes, resolved once per run. If the Belayline Agent Governance plugin
  is active, every call is governed by its gate (packs, tiers, approvals)
  and audit trail. Without it, Specflux Site Agent falls back to a built-in minimal
  gate: every call that changes the site still stops for a person to
  approve it on Specflux Site Agent’s own Runs screen before it runs; reads do not.
  A run’s mode is pinned at start and never changes underneath it — if the
  environment’s mode changes mid-run, the run fails cleanly instead of
  silently switching enforcement.
• Three kinds of park. An approval park (a governed write, resolved
  by a person), a question park (the model asks the user one structured
  question), and a plan park (the model proposes a numbered plan before
  its first write; once accepted, that plan’s tool set is a fence — calls
  outside it are refused until a new plan is accepted).
• Budgets bound every run. Steps, tool calls, tokens, questions and
  plans. A consumer may only lower a registered ceiling; running out of
  questions is not a failure — the model loses the ability to ask and
  proceeds on stated assumptions.
• Four bundled packs. Pages and posts (create/update/publish, with
  publish handled as its own governed step), site (navigation, front page,
  homepage patterns), and commerce (WooCommerce catalogue and order
  operations, when WooCommerce is active). Every content write is validated
  before anything is persisted: unrenderable or non-round-tripping markup,
  blocks outside the allowed set, disallowed tags or attributes, unresolved
  {{placeholder}} text, an unrecognised pattern shape, a slot count out of
  range, a page-shape rule (e.g. hero must come first), or a slug/title
  collision with an existing page or post — all refuse the whole write and
  persist nothing.
• Not for multisite. Specflux Site Agent refuses to activate on a WordPress
  multisite install.

External services

Specflux Site Agent itself makes two kinds of outbound request, both only while a
human is actively driving a run from their own browser session — Specflux Site Agent
never runs in the background.

Model calls (AI Client). Made through the WordPress AI Client (bundled
with WordPress 7.0+), using whichever provider your site has connected
under Settings → Connectors — commonly OpenAI, but any provider the AI
Client supports. On every model turn (at most one per tick), Specflux Site Agent
sends that provider:

• the run’s full conversation history so far (the goal, every model
  message, and every tool result already produced in the run);
• a system instruction assembled from the harness’s own operating rules,
  the active pack’s skills (e.g. a pack’s block-pattern vocabulary and
  copy constraints), and anything the consumer or specflux_site_agent_system_instruction
  filter contributes;
• the declared tool (Ability) schemas the run is allowed to call, and the
  results those tools return, which are fed back to the model on the next
  turn (capped at 32 KB per result by default, filterable via
  specflux_site_agent_tool_result_max_bytes).

No file, database or site content is sent beyond what a run’s own tool
calls read and return as results. Sending and handling this data is
governed by the connected provider’s own terms. The site owner chooses the
AI provider, so that provider’s terms and privacy policy apply; see, for
example, OpenAI’s:
https://openai.com/policies/row-terms-of-use/ and
https://openai.com/policies/row-privacy-policy/ — consult your specific
provider’s terms if you have connected a different one.

Stock photo search (Openverse). When a run searches for a stock image
(pages/site packs), Specflux Site Agent sends the model-generated search text as a
query string to Openverse’s public search API
(https://api.openverse.org/v1/images/) and to Openverse’s individual
image-detail endpoint when fetching a chosen result. No account
credentials, site content, or personal data are sent — only the search
terms and the id of a selected result. This runs only during an active,
human-driven run. See Openverse’s terms and privacy policy:
https://docs.openverse.org/terms_of_service.html and
https://openverse.org/privacy (Openverse is a WordPress.org project;
its privacy policy is https://wordpress.org/about/privacy/).

Image downloads. When a run imports a chosen stock photo or a generated
image, the plugin downloads the image file from the URL Openverse or the AI
provider returned (Openverse results are hosted by third-party sites such
as Flickr or Wikimedia Commons; an AI provider may instead return the image
data inline, in which case nothing is downloaded). Only the image URL is
requested, with no site data, and the file is then saved to your Media
Library.

Privacy

Specflux Site Agent stores each run in two custom tables: the ID of the user who
started it, the goal they typed, the conversation with the AI model, the
tool calls and their results, and timestamps. Runs stay until you remove
them or delete the plugin with the opt-in below.

Runs are sent off-site to the AI provider you connected, and search terms
are sent to Openverse; see “External services” above for exactly what.

Specflux Site Agent adds suggested text for your privacy policy under Settings →
Privacy → Policy Guide. It does not register a personal-data exporter or
eraser.

Deleting the plugin keeps your runs by default. To remove all Specflux Site Agent
data (both tables, its options, transients and per-user flags) when the
plugin is deleted, opt in first: wp option update specflux_site_agent_uninstall_delete_data 1,
then delete the plugin.

Developers

Extension API

SPECFLUX_SITE_AGENT_API_VERSION (currently 0.3.0, defined in specflux-site-agent.php) versions the declared

extension surface, independently of this plugin’s own Stable tag. Semver promise: a removal
or signature change needs a major bump; an addition needs a minor bump — this applies starting
at 0.3.0, even below 1.0.

The @api list: the Pack abstract class’s @api-tagged methods (name, roles,
abilityNamespaces, inputProperties, verbFor, objectIdKey/Prefix/ForWrite/ForRead,
roleCapabilities, withheldRoleNotice, verbMap, roleVerbs, ungrantableVerbs, governedNamespaces,
agentSafetyVerbMap, defaultBudget, skills, agentSafetyPack, validateCall, setupChecks,
runCapability, requiresAgentSafety, agentSafetyBindingError, guidesHash); the
Api\LayoutVocabulary facade (names, sectionSchema, validate, imageUrls, rulesLines); the
Skill/SkillSource/SetupCheck value types a pack constructs; and the specflux_site_agent_packs,
specflux_site_agent_run_skills and specflux_site_agent_default_budget filters. Every other filter, including
specflux_site_agent_can_tick and specflux_site_agent_http_consumers, is not part of this surface and may change
without a version bump.

REST (specflux-site-agent/v1) is the public @api consumer surface; admin-ajax is this plugin’s own private transport for its
bundled Runs screen and is not guaranteed to match REST’s shape.

Deprecation: a break goes through _deprecated_hook()/_deprecated_function() for at least
one minor release before removal at the next major. None exist yet.

See the “Extension API” section of README.md in the public repository,
https://github.com/specflux/specflux-site-agent, for the full reference, including how to
regenerate the reflection snapshot (tests/Api/public-surface.json there) that
enforces this.

Source code and build

The JavaScript in build/ is compiled from the sources in assets/src/ in
the public repository, https://github.com/specflux/specflux-site-agent. To rebuild it:

1. git clone https://github.com/specflux/specflux-site-agent && cd specflux-site-agent
2. npm ci

3. npm run build

   npm run build runs wp-scripts build and writes build/.