Specflux Site Agent

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

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

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,

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:

com/policies/row-terms-of-use/ and

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

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:

html and

org project;

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

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

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.

md in the public repository,

com/specflux/specflux-site-agent, for the full reference, including how to

json there) that

enforces this.

Source code and build

The JavaScript in build/ is compiled from the sources in assets/src/ in

com/specflux/specflux-site-agent. To rebuild it:

• git clone https://github.com/specflux/specflux-site-agent && cd specflux-site-agent

• npm ci

-

npm run build

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