@relvehq/agent-ready 0.2.1 → 0.3.1

package/dist/wp/relve-agent-ready/includes/class-relve-ar-refiner.php

@@ -0,0 +1,894 @@
+<?php
+/**
+ * Refiner: rewrite posts with Relve's prompt and the site's own OpenAI key.
+ *
+ * The prompt never leaves Relve's server, so the model call happens there:
+ * this class sends the rendered post (a small, complete HTML document) and
+ * its permalink to the Relve refine endpoint (contract:
+ * changes/agent-ready-byok-refine/contract.md) with the site's OpenAI key in
+ * the `X-OpenAI-Key` header, and stores the returned Markdown as the post's
+ * refined file, the same file the router serves first ("stored").
+ *
+ *   save / publish  -> transition_post_status -> one WP-Cron single event per
+ *                      post, 30 s later (never during the save request)
+ *   Rewrite all now -> a queue of post IDs in an option, 5 per cron run,
+ *                      the batch event reschedules itself until done
+ *   unpublish / delete -> the post's refined file is deleted
+ *
+ * Storage: the key lives in the settings option only. Per post, post meta
+ * holds the fingerprint (`_relve_ar_fingerprint`), the time of the last
+ * rewrite (`_relve_ar_refined_at`) and the stored file's path
+ * (`_relve_ar_refined_path`). Run state (last run, last error code, pause)
+ * lives in `relve_agent_ready_refine`; the batch queue in
+ * `relve_agent_ready_refine_queue`. Error codes are stored, never messages,
+ * and never the key.
+ *
+ * The key is only ever sent to an https endpoint (http is allowed for
+ * localhost only, for testing), with redirects off so it cannot be forwarded.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Bring-your-own-key rewrites through the Relve API.
+ */
+class Relve_AR_Refiner {
+
+	const DEFAULT_ENDPOINT = 'https://relvehq.com/api/agent-ready/v1/refine';
+
+	const HOOK_POST  = 'relve_ar_refine_post';
+	const HOOK_BATCH = 'relve_ar_refine_batch';
+
+	const STATE = 'relve_agent_ready_refine';
+	const QUEUE = 'relve_agent_ready_refine_queue';
+	const LOCK  = 'relve_ar_refine_lock';
+
+	const META_FINGERPRINT = '_relve_ar_fingerprint';
+	const META_REFINED_AT  = '_relve_ar_refined_at';
+	const META_PATH        = '_relve_ar_refined_path';
+
+	/** Posts per batch run. */
+	const BATCH_SIZE = 5;
+
+	/** Seconds between a save and its rewrite. */
+	const SAVE_DELAY = 30;
+
+	/** Seconds between batch runs. */
+	const BATCH_GAP = 5;
+
+	/** HTTP timeout in seconds (one model call: 5-30 s). */
+	const TIMEOUT = 90;
+
+	/** The contract's html limit in bytes. */
+	const MAX_HTML_BYTES = 2000000;
+
+	/** Errors that stop the batch until the key is fixed. */
+	const PAUSE_CODES = array( 'missing_key', 'openai_auth', 'openai_quota' );
+
+	/** Errors that make the batch wait and try the same post again. */
+	const WAIT_CODES = array( 'rate_limited', 'openai_rate_limited' );
+
+	/**
+	 * Register hooks (front end, admin and cron).
+	 *
+	 * @return void
+	 */
+	public static function init() {
+		add_action( 'transition_post_status', array( __CLASS__, 'on_transition' ), 10, 3 );
+		add_action( 'before_delete_post', array( __CLASS__, 'forget_post' ), 10, 1 );
+		add_action( self::HOOK_POST, array( __CLASS__, 'run_post' ), 10, 1 );
+		add_action( self::HOOK_BATCH, array( __CLASS__, 'run_batch' ) );
+	}
+
+	// ── endpoint ──────────────────────────────────────────────────────────
+
+	/**
+	 * Endpoint URL: RELVE_AR_REFINE_ENDPOINT, filterable.
+	 *
+	 * @return string
+	 */
+	public static function endpoint() {
+		$url = defined( 'RELVE_AR_REFINE_ENDPOINT' ) ? (string) RELVE_AR_REFINE_ENDPOINT : self::DEFAULT_ENDPOINT;
+		return (string) apply_filters( 'relve_ar_refine_endpoint', $url );
+	}
+
+	/**
+	 * May the key be sent to this URL? https only; http for localhost only.
+	 * No credentials in the URL.
+	 *
+	 * @param string $url Endpoint.
+	 * @return bool
+	 */
+	public static function endpoint_allowed( $url ) {
+		$p = wp_parse_url( (string) $url );
+		if ( ! is_array( $p ) || empty( $p['scheme'] ) || empty( $p['host'] ) || isset( $p['user'] ) || isset( $p['pass'] ) ) {
+			return false;
+		}
+		$scheme = strtolower( $p['scheme'] );
+		$host   = strtolower( trim( $p['host'], '[]' ) );
+		if ( 'https' === $scheme ) {
+			return true;
+		}
+		return 'http' === $scheme && in_array( $host, array( 'localhost', '127.0.0.1', '::1' ), true );
+	}
+
+	// ── paths ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Stored-file path for a permalink, the one the router looks up first.
+	 * Null for plain permalinks (?p=12), which have no path of their own.
+	 *
+	 * @param string $url Permalink.
+	 * @return string|null
+	 */
+	public static function rel_for_url( $url ) {
+		$p = wp_parse_url( (string) $url );
+		if ( ! is_array( $p ) || empty( $p['host'] ) || ! empty( $p['query'] ) ) {
+			return null;
+		}
+		$path = ( isset( $p['path'] ) && '' !== $p['path'] ) ? $p['path'] : '/';
+		return Relve_AR_Store::rel_for_path( $path );
+	}
+
+	// ── request ───────────────────────────────────────────────────────────
+
+	/**
+	 * A minimal, complete HTML document for the post: title, description,
+	 * canonical, JSON-LD, and the rendered content in <main><article>.
+	 *
+	 * @param WP_Post $post Post.
+	 * @param string  $url  Permalink.
+	 * @return string
+	 */
+	public static function build_html( $post, $url ) {
+		$title   = html_entity_decode( wp_strip_all_tags( get_the_title( $post ) ), ENT_QUOTES, 'UTF-8' );
+		$desc    = Relve_AR_Markdown_Builder::description_for( $post );
+		$content = Relve_AR_Markdown_Builder::render_content( $post );
+		$schema  = self::schema_for( $post, $url, $title, $desc );
+		$lang    = (string) get_bloginfo( 'language' );
+
+		$image    = '';
+		$thumb_id = function_exists( 'get_post_thumbnail_id' ) ? get_post_thumbnail_id( $post ) : 0;
+		if ( $thumb_id ) {
+			$src = wp_get_attachment_image_url( $thumb_id, 'full' );
+			if ( $src ) {
+				$alt   = (string) get_post_meta( $thumb_id, '_wp_attachment_image_alt', true );
+				$image = '<img src="' . self::h( $src ) . '" alt="' . self::h( '' === $alt ? $title : $alt ) . "\">\n";
+			}
+		}
+
+		$head = '<meta charset="utf-8">' . "\n"
+			. '<title>' . self::h( $title ) . "</title>\n";
+		if ( '' !== $desc ) {
+			$head .= '<meta name="description" content="' . self::h( $desc ) . "\">\n";
+		}
+		$head .= '<link rel="canonical" href="' . self::h( $url ) . "\">\n";
+		if ( null !== $schema ) {
+			$head .= '<script type="application/ld+json">' . $schema . "</script>\n";
+		}
+
+		return "<!doctype html>\n"
+			. '<html' . ( '' !== $lang ? ' lang="' . self::h( $lang ) . '"' : '' ) . ">\n"
+			. "<head>\n" . $head . "</head>\n"
+			. "<body>\n<main>\n<article>\n"
+			. '<h1>' . self::h( '' === $title ? 'Untitled' : $title ) . "</h1>\n"
+			. $image
+			. trim( $content ) . "\n"
+			. "</article>\n</main>\n</body>\n</html>\n";
+	}
+
+	/**
+	 * JSON-LD: Yoast's graph when Yoast provides one, else a simple Article.
+	 *
+	 * @param WP_Post $post  Post.
+	 * @param string  $url   Permalink.
+	 * @param string  $title Title.
+	 * @param string  $desc  Description.
+	 * @return string|null JSON, safe inside <script>.
+	 */
+	public static function schema_for( $post, $url, $title, $desc ) {
+		if ( function_exists( 'YoastSEO' ) ) {
+			try {
+				$meta  = YoastSEO()->meta->for_post( $post->ID );
+				$graph = $meta ? $meta->schema : null;
+				if ( is_array( $graph ) && $graph ) {
+					$json = self::json( $graph );
+					if ( null !== $json ) {
+						return $json;
+					}
+				}
+			} catch ( Throwable $e ) {
+				// Fall back to the simple Article below.
+				unset( $e );
+			}
+		}
+		$article = array(
+			'@context'      => 'https://schema.org',
+			'@type'         => 'Article',
+			'headline'      => $title,
+			'url'           => $url,
+			'datePublished' => (string) get_post_time( 'c', true, $post ),
+			'dateModified'  => (string) get_post_modified_time( 'c', true, $post ),
+		);
+		$author = html_entity_decode( (string) get_the_author_meta( 'display_name', $post->post_author ), ENT_QUOTES, 'UTF-8' );
+		if ( '' !== $author ) {
+			$article['author'] = array(
+				'@type' => 'Person',
+				'name'  => $author,
+			);
+		}
+		if ( '' !== $desc ) {
+			$article['description'] = $desc;
+		}
+		return self::json( $article );
+	}
+
+	/**
+	 * Request body for a post (contract fields).
+	 *
+	 * @param WP_Post        $post  Post.
+	 * @param string         $url   Permalink.
+	 * @param string         $model Model.
+	 * @param string         $rel   Stored-file path.
+	 * @param Relve_AR_Store $store Store.
+	 * @return array
+	 */
+	public static function build_payload( $post, $url, $model, $rel, $store ) {
+		$payload = array(
+			'url'   => $url,
+			'html'  => self::build_html( $post, $url ),
+			'model' => $model,
+		);
+		$site = self::cut( html_entity_decode( (string) get_bloginfo( 'name' ), ENT_QUOTES, 'UTF-8' ), 120 );
+		if ( '' !== $site ) {
+			$payload['siteName'] = $site;
+		}
+		// Only claim a fingerprint when its file is still there: after a
+		// "Clear" or a zip upload the server must write the page again.
+		$fp = (string) get_post_meta( $post->ID, self::META_FINGERPRINT, true );
+		if ( '' !== $fp && (string) get_post_meta( $post->ID, self::META_PATH, true ) === $rel && $store->exists( $rel ) ) {
+			$payload['previousFingerprint'] = $fp;
+		}
+		return $payload;
+	}
+
+	/**
+	 * wp_remote_post() arguments. The key goes in a header only.
+	 *
+	 * @param string $body JSON body.
+	 * @param string $key  OpenAI key.
+	 * @return array
+	 */
+	public static function request_args( $body, $key ) {
+		$ua = 'relve-agent-ready-wp/' . ( defined( 'RELVE_AR_VERSION' ) ? RELVE_AR_VERSION : '0' );
+		return array(
+			'method'      => 'POST',
+			'timeout'     => self::TIMEOUT,
+			'redirection' => 0, // A redirect must never carry the key elsewhere.
+			'sslverify'   => true,
+			'user-agent'  => $ua,
+			'headers'     => array(
+				'Content-Type' => 'application/json',
+				'Accept'       => 'application/json',
+				'X-OpenAI-Key' => $key,
+				'User-Agent'   => $ua,
+			),
+			'body'        => $body,
+			'data_format' => 'body',
+		);
+	}
+
+	// ── response ──────────────────────────────────────────────────────────
+
+	/**
+	 * Map an HTTP response to { status: ok|unchanged|error, code, markdown,
+	 * fingerprint, retry_after }. Only fixed codes come out; server messages
+	 * are dropped.
+	 *
+	 * @param array|WP_Error $response wp_remote_post() result.
+	 * @return array
+	 */
+	public static function parse_response( $response ) {
+		if ( is_wp_error( $response ) ) {
+			return self::result( 'error', 'network' );
+		}
+		$http = (int) wp_remote_retrieve_response_code( $response );
+		$body = json_decode( (string) wp_remote_retrieve_body( $response ), true );
+		if ( ! is_array( $body ) || ! isset( $body['status'] ) || ! is_string( $body['status'] ) ) {
+			return self::result( 'error', 'bad_response' );
+		}
+		$fingerprint = self::clean_fingerprint( isset( $body['fingerprint'] ) ? $body['fingerprint'] : '' );
+		switch ( $body['status'] ) {
+			case 'ok':
+				if ( 200 !== $http || ! isset( $body['markdown'] ) || ! is_string( $body['markdown'] ) || '' === trim( $body['markdown'] ) ) {
+					return self::result( 'error', 'bad_response' );
+				}
+				$r                = self::result( 'ok' );
+				$r['markdown']    = $body['markdown'];
+				$r['fingerprint'] = $fingerprint;
+				return $r;
+			case 'unchanged':
+				if ( 200 !== $http ) {
+					return self::result( 'error', 'bad_response' );
+				}
+				$r                = self::result( 'unchanged' );
+				$r['fingerprint'] = $fingerprint;
+				return $r;
+			case 'rejected':
+				return self::result( 'error', 'rejected' );
+			case 'error':
+				$code = ( isset( $body['error'] ) && is_string( $body['error'] ) && preg_match( '/^[a-z_]{1,40}$/', $body['error'] ) ) ? $body['error'] : 'upstream';
+				$r    = self::result( 'error', $code );
+				if ( isset( $body['retryAfter'] ) && is_numeric( $body['retryAfter'] ) ) {
+					$r['retry_after'] = (int) $body['retryAfter'];
+				} else {
+					$header = wp_remote_retrieve_header( $response, 'retry-after' );
+					if ( is_numeric( $header ) ) {
+						$r['retry_after'] = (int) $header;
+					}
+				}
+				return $r;
+		}
+		return self::result( 'error', 'bad_response' );
+	}
+
+	// ── running ───────────────────────────────────────────────────────────
+
+	/**
+	 * Rewrite one post now (cron context). Records the outcome.
+	 *
+	 * @param int $post_id Post ID.
+	 * @return array Result (see parse_response), status may also be "skipped".
+	 */
+	public static function refine_post( $post_id ) {
+		$post_id = (int) $post_id;
+		$s       = Relve_AR_Settings::get();
+		if ( '' === $s['openai_key'] ) {
+			return self::record_error( 'missing_key', $post_id );
+		}
+		$post = get_post( $post_id );
+		if ( ! Relve_AR_Router::servable_post( $post, $s['post_types'] ) ) {
+			self::forget_post( $post_id );
+			return self::result( 'skipped' );
+		}
+		$url = get_permalink( $post );
+		$rel = $url ? self::rel_for_url( $url ) : null;
+		if ( null === $rel ) {
+			return self::record_error( 'no_path', $post_id );
+		}
+		$endpoint = self::endpoint();
+		if ( ! self::endpoint_allowed( $endpoint ) ) {
+			return self::record_error( 'bad_endpoint', $post_id );
+		}
+
+		$store   = new Relve_AR_Store();
+		$payload = self::build_payload( $post, $url, $s['refine_model'], $rel, $store );
+		if ( strlen( $payload['html'] ) > self::MAX_HTML_BYTES ) {
+			return self::record_error( 'too_large', $post_id );
+		}
+		$body = self::json( $payload );
+		if ( null === $body ) {
+			return self::record_error( 'bad_request', $post_id );
+		}
+
+		$r = self::parse_response( wp_remote_post( $endpoint, self::request_args( $body, $s['openai_key'] ) ) );
+		return self::apply( $r, $post_id, $rel, $store );
+	}
+
+	/**
+	 * Act on a parsed response.
+	 *
+	 * @param array          $r       Parsed response.
+	 * @param int            $post_id Post ID.
+	 * @param string         $rel     Stored-file path.
+	 * @param Relve_AR_Store $store   Store.
+	 * @return array
+	 */
+	public static function apply( $r, $post_id, $rel, $store ) {
+		if ( 'unchanged' === $r['status'] ) {
+			self::touch_state( array() );
+			return $r;
+		}
+		if ( 'ok' !== $r['status'] ) {
+			$out = self::record_error( $r['code'], $post_id );
+			$out['retry_after'] = $r['retry_after'];
+			return $out;
+		}
+		if ( ! preg_match( '//u', $r['markdown'] ) ) {
+			return self::record_error( 'bad_response', $post_id );
+		}
+		$store->ensure();
+		if ( ! $store->put( $rel, $r['markdown'] ) ) {
+			return self::record_error( 'store_failed', $post_id );
+		}
+		$old = (string) get_post_meta( $post_id, self::META_PATH, true );
+		if ( '' !== $old && $old !== $rel ) {
+			$store->delete( $old ); // The permalink changed.
+		}
+		if ( '' !== $r['fingerprint'] ) {
+			update_post_meta( $post_id, self::META_FINGERPRINT, $r['fingerprint'] );
+		} else {
+			delete_post_meta( $post_id, self::META_FINGERPRINT );
+		}
+		update_post_meta( $post_id, self::META_REFINED_AT, time() );
+		update_post_meta( $post_id, self::META_PATH, $rel );
+		self::touch_state( array() );
+		unset( $r['markdown'] );
+		return $r;
+	}
+
+	/**
+	 * Cron: one post after a save.
+	 *
+	 * @param int $post_id Post ID.
+	 * @return void
+	 */
+	public static function run_post( $post_id ) {
+		self::extend_time();
+		self::refine_post( (int) $post_id );
+	}
+
+	/**
+	 * Cron: the next BATCH_SIZE posts of the "Rewrite all now" queue.
+	 *
+	 * @return array { processed: int, remaining: int, stopped: ''|paused|waiting|locked }
+	 */
+	public static function run_batch() {
+		$out = array(
+			'processed' => 0,
+			'remaining' => 0,
+			'stopped'   => '',
+		);
+		$state = self::state();
+		$q     = self::queue();
+		$out['remaining'] = count( $q['ids'] );
+		if ( '' !== $state['paused'] ) {
+			$out['stopped'] = 'paused';
+			return $out;
+		}
+		if ( get_transient( self::LOCK ) ) {
+			$out['stopped'] = 'locked';
+			return $out;
+		}
+		set_transient( self::LOCK, 1, 900 );
+		self::extend_time();
+		try {
+			while ( $q['ids'] && $out['processed'] < self::BATCH_SIZE ) {
+				$id = (int) array_shift( $q['ids'] );
+				$r  = self::refine_post( $id );
+				if ( 'error' === $r['status'] && in_array( $r['code'], self::PAUSE_CODES, true ) ) {
+					array_unshift( $q['ids'], $id );
+					self::save_queue( $q );
+					self::pause( $r['code'] );
+					$out['stopped'] = 'paused';
+					break;
+				}
+				if ( 'error' === $r['status'] && in_array( $r['code'], self::WAIT_CODES, true ) ) {
+					array_unshift( $q['ids'], $id );
+					self::save_queue( $q );
+					$wait = $r['retry_after'] > 0 ? $r['retry_after'] : 60;
+					self::schedule_batch( time() + max( 30, min( 3600, $wait ) ) );
+					$out['stopped'] = 'waiting';
+					break;
+				}
+				++$q['done'];
+				++$out['processed'];
+				self::save_queue( $q );
+			}
+			if ( '' === $out['stopped'] ) {
+				if ( $q['ids'] ) {
+					self::schedule_batch( time() + self::BATCH_GAP );
+				} else {
+					delete_option( self::QUEUE );
+					self::touch_state(
+						array(
+							'last_batch' => array(
+								'done'  => $q['done'],
+								'total' => $q['total'],
+								'at'    => time(),
+							),
+						)
+					);
+				}
+			}
+		} finally {
+			delete_transient( self::LOCK );
+		}
+		$out['remaining'] = count( $q['ids'] );
+		return $out;
+	}
+
+	/**
+	 * "Rewrite all now": queue every published post of the enabled types.
+	 *
+	 * @return int Posts queued (0 without a key).
+	 */
+	public static function start_all() {
+		$s = Relve_AR_Settings::get();
+		if ( '' === $s['openai_key'] || ! $s['post_types'] ) {
+			return 0;
+		}
+		$ids = get_posts(
+			array(
+				'post_type'        => $s['post_types'],
+				'post_status'      => 'publish',
+				'has_password'     => false,
+				'numberposts'      => -1,
+				'fields'           => 'ids',
+				'orderby'          => 'ID',
+				'order'            => 'ASC',
+				'suppress_filters' => true,
+				'no_found_rows'    => true,
+			)
+		);
+		$ids = array_values( array_unique( array_map( 'intval', (array) $ids ) ) );
+		if ( ! $ids ) {
+			delete_option( self::QUEUE );
+			return 0;
+		}
+		self::save_queue(
+			array(
+				'ids'   => $ids,
+				'total' => count( $ids ),
+				'done'  => 0,
+			)
+		);
+		self::touch_state(
+			array(
+				'paused'     => '',
+				'last_error' => '',
+			)
+		);
+		wp_clear_scheduled_hook( self::HOOK_BATCH );
+		self::schedule_batch( time() );
+		return count( $ids );
+	}
+
+	// ── post lifecycle ────────────────────────────────────────────────────
+
+	/**
+	 * transition_post_status: schedule a rewrite for published posts; forget
+	 * the file when a post leaves "publish".
+	 *
+	 * @param string  $new_status New status.
+	 * @param string  $old_status Old status.
+	 * @param WP_Post $post       Post.
+	 * @return void
+	 */
+	public static function on_transition( $new_status, $old_status, $post ) {
+		if ( ! ( $post instanceof WP_Post ) || self::is_revision_or_autosave( $post ) ) {
+			return;
+		}
+		if ( 'publish' !== $new_status ) {
+			if ( 'publish' === $old_status ) {
+				self::forget_post( $post->ID );
+			}
+			return;
+		}
+		self::maybe_schedule( $post );
+	}
+
+	/**
+	 * Schedule one rewrite for a published post (deduplicated).
+	 *
+	 * @param WP_Post $post Post.
+	 * @return bool Whether an event was scheduled.
+	 */
+	public static function maybe_schedule( $post ) {
+		if ( ! ( $post instanceof WP_Post ) || self::is_revision_or_autosave( $post ) ) {
+			return false;
+		}
+		$s = Relve_AR_Settings::get();
+		if ( ! $s['enabled'] || ! $s['refine_on_save'] || '' === $s['openai_key'] ) {
+			return false;
+		}
+		if ( ! Relve_AR_Router::servable_post( $post, $s['post_types'] ) ) {
+			self::forget_post( $post->ID ); // Now password-protected or no longer public.
+			return false;
+		}
+		$args = array( (int) $post->ID );
+		if ( false !== wp_next_scheduled( self::HOOK_POST, $args ) ) {
+			return false;
+		}
+		return true === wp_schedule_single_event( time() + self::SAVE_DELAY, self::HOOK_POST, $args );
+	}
+
+	/**
+	 * Revision, autosave, or an autosave request.
+	 *
+	 * @param WP_Post $post Post.
+	 * @return bool
+	 */
+	private static function is_revision_or_autosave( $post ) {
+		if ( 'revision' === $post->post_type || ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) ) {
+			return true;
+		}
+		return (bool) wp_is_post_revision( $post ) || (bool) wp_is_post_autosave( $post );
+	}
+
+	/**
+	 * Delete a post's refined file and its meta; drop its pending event.
+	 *
+	 * @param int $post_id Post ID.
+	 * @return void
+	 */
+	public static function forget_post( $post_id ) {
+		$post_id = (int) $post_id;
+		$rel     = (string) get_post_meta( $post_id, self::META_PATH, true );
+		if ( '' !== $rel ) {
+			$store = new Relve_AR_Store();
+			$store->delete( $rel );
+		}
+		delete_post_meta( $post_id, self::META_FINGERPRINT );
+		delete_post_meta( $post_id, self::META_REFINED_AT );
+		delete_post_meta( $post_id, self::META_PATH );
+		wp_clear_scheduled_hook( self::HOOK_POST, array( $post_id ) );
+	}
+
+	/**
+	 * Drop every post's refine meta (after "Clear refined files").
+	 *
+	 * @return void
+	 */
+	public static function forget_all_meta() {
+		delete_post_meta_by_key( self::META_FINGERPRINT );
+		delete_post_meta_by_key( self::META_REFINED_AT );
+		delete_post_meta_by_key( self::META_PATH );
+	}
+
+	/**
+	 * The key was replaced or removed: lift a pause, resume a waiting queue.
+	 *
+	 * @param bool $has_key Whether a key is now saved.
+	 * @return void
+	 */
+	public static function key_changed( $has_key ) {
+		self::touch_state( array( 'paused' => '' ) );
+		$q = self::queue();
+		if ( $has_key && $q['ids'] ) {
+			self::schedule_batch( time() + self::BATCH_GAP );
+		}
+	}
+
+	/**
+	 * Deactivation: no scheduled work left behind.
+	 *
+	 * @return void
+	 */
+	public static function unschedule_all() {
+		wp_unschedule_hook( self::HOOK_POST );
+		wp_unschedule_hook( self::HOOK_BATCH );
+		delete_option( self::QUEUE );
+		delete_transient( self::LOCK );
+	}
+
+	// ── state ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Run state.
+	 *
+	 * @return array { last_run, last_error, last_error_at, last_error_post, paused, last_batch }
+	 */
+	public static function state() {
+		$stored = get_option( self::STATE, array() );
+		$s      = array_merge(
+			array(
+				'last_run'        => 0,
+				'last_error'      => '',
+				'last_error_at'   => 0,
+				'last_error_post' => 0,
+				'paused'          => '',
+				'last_batch'      => null,
+			),
+			is_array( $stored ) ? $stored : array()
+		);
+		$s['paused']     = is_string( $s['paused'] ) ? $s['paused'] : '';
+		$s['last_error'] = is_string( $s['last_error'] ) ? $s['last_error'] : '';
+		return $s;
+	}
+
+	/**
+	 * Batch queue.
+	 *
+	 * @return array { ids: int[], total: int, done: int }
+	 */
+	public static function queue() {
+		$q = get_option( self::QUEUE, array() );
+		$q = is_array( $q ) ? $q : array();
+		return array(
+			'ids'   => isset( $q['ids'] ) && is_array( $q['ids'] ) ? array_values( array_map( 'intval', $q['ids'] ) ) : array(),
+			'total' => isset( $q['total'] ) ? (int) $q['total'] : 0,
+			'done'  => isset( $q['done'] ) ? (int) $q['done'] : 0,
+		);
+	}
+
+	/**
+	 * Number of posts with a rewritten file.
+	 *
+	 * @return int
+	 */
+	public static function count_rewritten() {
+		$ids = get_posts(
+			array(
+				'post_type'        => 'any',
+				'post_status'      => 'any',
+				'meta_key'         => self::META_REFINED_AT, // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- admin page only.
+				'numberposts'      => -1,
+				'fields'           => 'ids',
+				'suppress_filters' => true,
+				'no_found_rows'    => true,
+			)
+		);
+		return is_array( $ids ) ? count( $ids ) : 0;
+	}
+
+	/**
+	 * Plain-English label for an error code (admin).
+	 *
+	 * @param string $code Code.
+	 * @return string
+	 */
+	public static function error_label( $code ) {
+		$labels = array(
+			'missing_key'         => __( 'No OpenAI key is saved.', 'relve-agent-ready' ),
+			'openai_auth'         => __( 'OpenAI rejected the key. Replace it below.', 'relve-agent-ready' ),
+			'openai_quota'        => __( 'The OpenAI account has no quota or billing left.', 'relve-agent-ready' ),
+			'openai_rate_limited' => __( 'OpenAI rate-limited the key; it will be retried.', 'relve-agent-ready' ),
+			'rate_limited'        => __( 'Relve rate-limited this site; it will be retried.', 'relve-agent-ready' ),
+			'rejected'            => __( 'The rewrite did not pass Relve\'s check; the WordPress Markdown is served.', 'relve-agent-ready' ),
+			'too_little_text'     => __( 'The page has too little text to rewrite.', 'relve-agent-ready' ),
+			'too_large'           => __( 'The page is too large to rewrite.', 'relve-agent-ready' ),
+			'bad_request'         => __( 'The request was refused as invalid.', 'relve-agent-ready' ),
+			'upstream'            => __( 'OpenAI returned an error.', 'relve-agent-ready' ),
+			'timeout'             => __( 'The model took too long.', 'relve-agent-ready' ),
+			'network'             => __( 'Relve could not be reached.', 'relve-agent-ready' ),
+			'bad_response'        => __( 'Relve sent an unexpected answer.', 'relve-agent-ready' ),
+			'bad_endpoint'        => __( 'The endpoint is not https; the key was not sent.', 'relve-agent-ready' ),
+			'no_path'             => __( 'Plain permalinks (?p=) have no path to store a file under.', 'relve-agent-ready' ),
+			'store_failed'        => __( 'The file could not be written. Check that wp-content/uploads is writable.', 'relve-agent-ready' ),
+		);
+		return isset( $labels[ $code ] ) ? $labels[ $code ] : __( 'Unexpected error.', 'relve-agent-ready' );
+	}
+
+	// ── internals ─────────────────────────────────────────────────────────
+
+	/**
+	 * A result array.
+	 *
+	 * @param string $status ok|unchanged|error|skipped.
+	 * @param string $code   Error code.
+	 * @return array
+	 */
+	private static function result( $status, $code = '' ) {
+		return array(
+			'status'      => $status,
+			'code'        => $code,
+			'markdown'    => null,
+			'fingerprint' => '',
+			'retry_after' => 0,
+		);
+	}
+
+	/**
+	 * Record an error code (never a message, never the key).
+	 *
+	 * @param string $code    Code.
+	 * @param int    $post_id Post ID.
+	 * @return array
+	 */
+	private static function record_error( $code, $post_id ) {
+		$code = preg_match( '/^[a-z_]{1,40}$/', (string) $code ) ? (string) $code : 'upstream';
+		self::touch_state(
+			array(
+				'last_error'      => $code,
+				'last_error_at'   => time(),
+				'last_error_post' => (int) $post_id,
+			)
+		);
+		return self::result( 'error', $code );
+	}
+
+	/**
+	 * Pause the batch.
+	 *
+	 * @param string $code Code.
+	 * @return void
+	 */
+	private static function pause( $code ) {
+		self::touch_state( array( 'paused' => $code ) );
+	}
+
+	/**
+	 * Merge into the state and stamp last_run.
+	 *
+	 * @param array $changes Changes.
+	 * @return void
+	 */
+	private static function touch_state( $changes ) {
+		$s             = array_merge( self::state(), $changes );
+		$s['last_run'] = time();
+		update_option( self::STATE, $s, false );
+	}
+
+	/**
+	 * Save the queue (not autoloaded).
+	 *
+	 * @param array $q Queue.
+	 * @return void
+	 */
+	private static function save_queue( $q ) {
+		update_option( self::QUEUE, $q, false );
+	}
+
+	/**
+	 * Schedule the batch event unless one is pending.
+	 *
+	 * @param int $when Timestamp.
+	 * @return void
+	 */
+	private static function schedule_batch( $when ) {
+		if ( false === wp_next_scheduled( self::HOOK_BATCH ) ) {
+			wp_schedule_single_event( $when, self::HOOK_BATCH );
+		}
+	}
+
+	/**
+	 * A model call can take 30 s; a batch of five more. Lift the time limit
+	 * where the host allows it (cron runs only).
+	 *
+	 * @return void
+	 */
+	private static function extend_time() {
+		$disabled = (string) ini_get( 'disable_functions' );
+		if ( function_exists( 'set_time_limit' ) && false === strpos( $disabled, 'set_time_limit' ) ) {
+			set_time_limit( 600 );
+		}
+	}
+
+	/**
+	 * Fingerprint as sent by the server, or "".
+	 *
+	 * @param mixed $fp Value.
+	 * @return string
+	 */
+	private static function clean_fingerprint( $fp ) {
+		return ( is_string( $fp ) && preg_match( '/^[A-Za-z0-9:_\-]{1,128}$/', $fp ) ) ? $fp : '';
+	}
+
+	/**
+	 * JSON safe inside <script> and for invalid UTF-8; null on failure.
+	 *
+	 * @param mixed $data Data.
+	 * @return string|null
+	 */
+	private static function json( $data ) {
+		$j = json_encode( $data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_HEX_TAG | JSON_INVALID_UTF8_SUBSTITUTE ); // phpcs:ignore WordPress.WP.AlternativeFunctions.json_encode_json_encode -- flags wp_json_encode does not add.
+		return false === $j ? null : $j;
+	}
+
+	/**
+	 * HTML-escape.
+	 *
+	 * @param string $s Text.
+	 * @return string
+	 */
+	private static function h( $s ) {
+		return htmlspecialchars( (string) $s, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8' );
+	}
+
+	/**
+	 * Cut to $max characters.
+	 *
+	 * @param string $s   Text.
+	 * @param int    $max Max.
+	 * @return string
+	 */
+	private static function cut( $s, $max ) {
+		$s = trim( (string) $s );
+		return function_exists( 'mb_substr' ) ? mb_substr( $s, 0, $max, 'UTF-8' ) : substr( $s, 0, $max );
+	}
+}