=== Raqvio Agent Guardrails for WooCommerce ===
Contributors: raqvio
Tags: ai, woocommerce, mcp, security, audit log
Requires at least: 6.9
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Decide what AI agents may do on your WooCommerce store: per-agent permissions, an emergency kill switch and a redacted audit log.

== Description ==

AI agents can now work on your WordPress site directly. Since WordPress 6.9, plugins register *abilities* — "update a product", "change an order status" — and agents such as Claude Desktop or your own scripts can discover and run them over the REST API or MCP. WooCommerce exposes products and orders this way too.

That is powerful, and a little unnerving. Out of the box there is no way to say "this agent may read orders but never refund one", no off switch, and no record of what an agent actually did.

Raqvio Agent Guardrails adds that missing layer. It sits in front of every ability your site runs, works out which agent is calling, decides whether the call is allowed, and writes it down.

= Features =

* **See every ability on your site.** Abilities from WordPress, WooCommerce and other plugins are listed in one place, each classified as Read, Write, Financial or Destructive. Disagree with a classification? Override it. Mark an ability as sensitive and its input is never logged.
* **Name your agents.** Tie an application password, or a dedicated WordPress user, to a named agent. Add as many agents as you need. A built-in "Site AI" agent covers AI features running inside WordPress.
* **Allow or deny per agent.** Choose, ability by ability, what each agent may do. Agents you haven't set up get safe defaults: they can read, but anything that writes, moves money or deletes is denied.
* **An emergency kill switch.** One click in the admin bar blocks every agent at once. From the dashboard you can also block agents for one hour, after which the switch turns itself off.
* **A redacted audit log.** Every agent call is recorded with the agent, the channel (MCP, REST or internal), the decision and the result. Before anything is stored, values in fields named like passwords, tokens, keys or card data are removed, and emails, phone numbers and addresses are masked. You choose how long entries are kept, from 1 to 365 days (30 by default).
* **A credential and exposure check.** Find out whether your AI provider keys live in the database or safely in `wp-config.php` or environment variables — without Raqvio Agent Guardrails ever reading them — plus which abilities are publicly exposed and which administrators have application passwords.
* **A catalog readiness score.** With WooCommerce, scan your catalog and get a 0–100 score per product and for the store, based on what AI shopping agents need: descriptions, images and alt text, SKU, GTIN/MPN/brand, attributes, variations, price and stock, and title quality. A separate check tells you whether your product pages carry Product JSON-LD.
* **Help for well-behaved agents.** The `raqvio-ag/get-my-permissions` ability lets an agent ask what it is allowed to do before it tries.
* **A refund ability that stays under your control.** `raqvio-ag/order-create-refund` (WooCommerce 10.9 or newer) lets an agent refund an order by amount or per line item, with optional restock. It is classified as Financial, so no agent can use it until you allow it, and money only goes back through the payment gateway if the agent explicitly asks and the gateway supports automatic refunds.
* **Works with WooCommerce's MCP endpoint.** Agents that connect with WooCommerce REST API keys are identified by the key's user, and WooCommerce's MCP tools show up in the permission matrix like any other ability.

When an agent is blocked it gets a clear error (`raqvio_ag_denied`, or `raqvio_ag_blocked` while the kill switch is on) with a reason that starts with "Blocked by Raqvio Agent Guardrails:", so both the agent and you know why.

= Requirements =

Raqvio Agent Guardrails needs WordPress 6.9 and PHP 8.1. To actually **block** agents it needs WordPress 7.1, which added the hook Raqvio Agent Guardrails uses to stop an ability before it runs. On WordPress 6.9 and 7.0 it runs in audit-only mode: it logs every agent call and what it *would* have decided, and tells you so.

WooCommerce is optional. Governance works for any ability; the catalog readiness score and the refund ability need WooCommerce.

== Installation ==

1. Install Raqvio Agent Guardrails from **Plugins → Add New Plugin** and activate it. On multisite, activate it on each site rather than network-wide.
2. Open **Raqvio Agent Guardrails → Settings** and look through the hardening checklist at the bottom.
3. Create a dedicated WordPress user for your agent. Give it only the capabilities the agent needs — Raqvio Agent Guardrails narrows what a user can do, it never grants capabilities. The "AI Agent (Raqvio Agent Guardrails)" role is a read-only starting point; a role such as Shop Manager lets an agent work with products and orders.
4. Edit that user and create an **application password** for the agent.
5. In **Raqvio Agent Guardrails → Agents**, click **Add agent**, bind it to that application password, then open **Permissions** and allow what the agent should be able to do.
6. Connect your AI client with the user name and application password, through the WordPress Abilities REST API (`/wp-json/wp-abilities/v1/`) or an MCP server. Your agent's calls appear in **Raqvio Agent Guardrails → Audit Log**.

Using WooCommerce's MCP endpoint instead? Bind the agent to the WordPress user who owns the WooCommerce API key. Step-by-step guides, including a tested Claude Desktop setup, are at [guardrails.raqvio.com/docs](https://guardrails.raqvio.com/docs/).

== Frequently Asked Questions ==

= Does Raqvio Agent Guardrails work without WooCommerce? =

Yes. It governs any ability registered through the WordPress Abilities API. The catalog readiness score and the refund ability simply don't appear until WooCommerce is active.

= Are people using wp-admin affected? =

No, not by default. Raqvio Agent Guardrails only governs agent traffic: calls made with an application password or over MCP, users with the "AI Agent (Raqvio Agent Guardrails)" role, and the built-in Site AI. If you want logged-in people to follow the same rules, turn on "Govern all ability executions" in Settings.

= What happens to agents I haven't set up? =

They are treated as unknown agents and get the defaults from Settings: Read abilities are allowed; Write, Financial and Destructive ones are denied. You can change each of those.

= Why don't I see my agent's calls in the audit log? =

Make sure the calls really come from an agent. A request from your own logged-in browser session isn't governed unless "Govern all ability executions" is on. On WordPress 6.9 and 7.0, entries are marked "(not enforced)" because nothing can be blocked yet.

= Can agents issue refunds? =

Only if you let them. The refund ability is Financial, so it is denied until you allow it for a specific agent. By default a refund is only recorded in WooCommerce; it returns money through the payment gateway only when the agent asks for that and the gateway supports it. Developers can remove the ability entirely with `add_filter( 'raqvio_ag_register_refund_ability', '__return_false' );`.

= Can a refund be undone? =

No. Refunds and payments are final, and Raqvio Agent Guardrails says so wherever it matters. If you want a person to look at larger refunds first, Raqvio Agent Guardrails Pro can hold them for approval.

= Can an agent switch off its own guardrails? =

No. Raqvio Agent Guardrails's settings can only be changed from a logged-in wp-admin session of someone allowed to manage Raqvio Agent Guardrails. Requests made with an application password are always refused, even for administrator accounts.

= Does Raqvio Agent Guardrails read my AI API keys? =

No. The hardening check only reports *where* a key is configured — environment variable, `wp-config.php` constant, or database. For the database it runs a `LENGTH()` query, so the key itself never leaves MySQL.

= Will it slow my site down? =

Raqvio Agent Guardrails only does work when an ability runs. Its policies are compiled and cached, and the test suite checks that the overhead per call stays under 5 ms at the 95th percentile, including writing the audit entry.

= What happens to my data if I delete the plugin? =

Deactivating keeps everything. Deleting the plugin keeps your data too, unless you first turn on "Delete all Raqvio Agent Guardrails data when the plugin is uninstalled" in Settings.

== Privacy ==

Everything Raqvio Agent Guardrails stores stays in your own database:

* **Audit log:** time, agent, WordPress user ID, channel, ability, risk, decision, status, duration, a short result summary, and the ability input after redaction (see above). Abilities you mark as sensitive never have their input stored. Entries older than the retention period you set in Settings (30 days by default) are deleted automatically.
* **Agents:** name, description, status, and the ID of the bound application password or user. The application password itself is never read or stored.
* **Catalog readiness:** a score and a list of issues per product.

== Source code and libraries ==

The compiled admin app in `build/` is generated from the readable JavaScript and SCSS sources included in this plugin under `assets/src/`. The build configuration (`package.json` and `webpack.config.js`) is included too. To rebuild it, run `npm install` and then `npm run build` in the plugin folder (Node.js 20 or newer). The build uses [@wordpress/scripts](https://www.npmjs.com/package/@wordpress/scripts).

Bundled third-party libraries:

* [Action Scheduler](https://github.com/woocommerce/action-scheduler) 4.2.0 by WooCommerce (GPLv3), in `vendor/woocommerce/action-scheduler/`. It runs background jobs when WooCommerce is not active. If another plugin loads a newer copy, Action Scheduler uses that one.
* [Freemius WordPress SDK](https://github.com/Freemius/wordpress-sdk) 2.13.4 (GPLv3), in `freemius/`. Its compiled pricing page script, `freemius/assets/js/pricing/freemius-pricing.js`, is built from [github.com/Freemius/pricing-page](https://github.com/Freemius/pricing-page). When several plugins bundle the SDK, it loads only the newest copy.

== Screenshots ==

1. The dashboard: kill switch, the last 24 hours of agent activity, abilities by risk, agents, hardening and catalog readiness.
2. Every ability on the site, with its risk level, exposure and overrides.
3. An agent's permissions, ability by ability.
4. The audit log, with redacted input for each call.
5. The catalog readiness score and the issues behind it.
6. Settings, with the credential and exposure hardening checklist.

== Changelog ==

= 1.0.1 =
* Improvements and minor bug fix.

= 1.0.0 =
* Initial release.
