__( 'Agent publishing', 'acadium-agent-publisher' ),
'description' => __( 'Draft, review, publish and update posts, upload images and look up taxonomy terms, within the rules set by the site owner.', 'acadium-agent-publisher' ),
) );
}
/**
* Annotations are hints for clients, but core's Abilities REST API also
* derives the HTTP method from them: readonly → GET, destructive AND
* idempotent → DELETE (input only from the query string), otherwise POST.
* Write abilities therefore never combine destructive with idempotent,
* so they all take a JSON body via POST.
*
* Exposure flags. `public` is the WordPress 7.1+ switch (it also seeds
* show_in_rest); `mcp.public` and `show_in_rest` make the same intent
* explicit on 6.9 / 7.0 and for the MCP Adapter.
*/
private static function meta( $readonly, $destructive, $idempotent ) {
return array(
'annotations' => array(
'readonly' => $readonly,
'destructive' => $destructive,
'idempotent' => $idempotent,
),
'public' => true,
'show_in_rest' => true,
'mcp' => array( 'public' => true ),
);
}
public static function register_abilities() {
$post_types = self::post_types();
$meta_keys = self::meta_keys();
$post_fields = array(
'title' => array( 'type' => 'string', 'description' => 'Title (plain text).' ),
'content' => array( 'type' => 'string', 'description' => 'Body as HTML. Use the markup the site\'s editor produces for this type (see get-capabilities > content_types > block_editor): plain HTML (
,
,
, ) for the classic editor, or block markup () for the block editor. When editing an existing page, keep its block structure and markup and change only what was asked; to change part of existing content, use edits instead of resending it. If the connected person\'s role can\'t post unfiltered HTML (Authors, Contributors), scripts, iframes and inline SVG are removed.' ),
'excerpt' => array( 'type' => 'string', 'description' => 'Optional summary shown in listings and search results.' ),
'slug' => array( 'type' => 'string', 'description' => 'Optional URL slug. Generated from the title when omitted.' ),
'categories' => array( 'type' => 'array', 'items' => array( 'type' => 'integer' ), 'description' => 'Posts only. Category IDs (see agent-publisher/list-terms). Replaces existing categories.' ),
'tags' => array( 'type' => 'array', 'items' => array( 'type' => 'string' ), 'description' => 'Posts only. Tag names. Missing tags are created. Replaces existing tags.' ),
'parent' => array( 'type' => 'integer', 'description' => 'Pages only. ID of the parent page (0 for none); sets the URL, e.g. /services/seo/. Find pages with find-posts.' ),
'menu_order' => array( 'type' => 'integer', 'description' => 'Pages only. Order among sibling pages.' ),
'template' => array( 'type' => 'string', 'description' => 'Pages only. Page template file from get-capabilities > content_types > page > templates, or "default".' ),
'featured_media' => array( 'type' => 'integer', 'description' => 'ID of an image already in the Media Library to use as the featured image. To add a new image, use featured_image on create-post, or agent-publisher/upload-media.' ),
);
// Only offer custom fields when a site enables some. An empty
// `properties` would be encoded as a JSON array ([]), an invalid
// schema that makes MCP clients such as Claude Desktop drop the tool.
if ( $meta_keys ) {
$post_fields['meta'] = array(
'type' => 'object',
'description' => 'Custom fields. Allowed keys: ' . implode( ', ', $meta_keys ) . '.',
'properties' => array_fill_keys( $meta_keys, array( 'type' => 'string' ) ),
'additionalProperties' => false,
);
}
$post_output = array(
'type' => 'object',
'properties' => array(
'id' => array( 'type' => 'integer' ),
'type' => array( 'type' => 'string', 'description' => 'post or page.' ),
'status' => array( 'type' => 'string' ),
'title' => array( 'type' => 'string' ),
'author' => array( 'type' => 'string', 'description' => 'Display name of the author (edits keep the original author).' ),
'edit_url' => array( 'type' => 'string', 'description' => 'wp-admin editor URL for a human reviewer.' ),
'preview_url' => array( 'type' => 'string', 'description' => 'Preview URL (requires being logged in).' ),
'featured_image' => array( 'type' => 'object', 'description' => 'The featured image: id, url, width, height, alt, and the sizes WordPress generated from it (name => url, width, height), to check how it is cropped.' ),
'image_warnings' => array( 'type' => 'array', 'items' => array( 'type' => 'string' ), 'description' => 'Problems with the featured image for this site (too small, or a shape the theme crops); see get-capabilities > images.' ),
),
);
$id_only = array(
'type' => 'object',
'properties' => array( 'id' => array( 'type' => 'integer', 'description' => 'Post ID.' ) ),
'required' => array( 'id' ),
'additionalProperties' => false,
);
$publish_output = array(
'type' => 'object',
'properties' => array_merge( $post_output['properties'], array(
'link' => array( 'type' => 'string', 'description' => 'Public URL (for scheduled posts, live from the scheduled time).' ),
'date' => array( 'type' => 'string', 'description' => 'Publication date (site time, ISO 8601).' ),
) ),
);
wp_register_ability( 'agent-publisher/get-capabilities', array(
'label' => __( 'Get what the agent may do', 'acadium-agent-publisher' ),
'description' => 'Returns this site\'s rules for agents: the publishing mode (drafts only, submit for review, publish, or publish and edit live posts), which actions are therefore allowed, and the pre-publish checks (featured image required, allowed categories, daily limit). Call this first so you only offer actions the site allows.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => new stdClass(),
'additionalProperties' => false,
'default' => array(),
),
'output_schema' => array(
'type' => 'object',
'properties' => array(
'mode' => array( 'type' => 'string', 'enum' => Agent_Publisher_Policy::MODES ),
'mode_label' => array( 'type' => 'string' ),
'allowed' => array( 'type' => 'object' ),
'checks' => array( 'type' => 'object' ),
'content_types' => array( 'type' => 'object', 'description' => 'For each type (post, page): whether you may create, edit others\' content and publish it, whether it uses the block editor, and (pages) the available templates.' ),
'images' => array( 'type' => 'object', 'description' => 'How to add images and what this site needs: accepted types, size limits, generated sizes, minimum width, aspect ratios the theme crops to, and guidance from the site owner.' ),
'user' => array( 'type' => 'object' ),
),
),
'execute_callback' => array( __CLASS__, 'get_capabilities' ),
'permission_callback' => function () {
return current_user_can( 'edit_posts' );
},
'meta' => self::meta( true, false, true ),
) );
wp_register_ability( 'agent-publisher/list-terms', array(
'label' => __( 'List categories or tags', 'acadium-agent-publisher' ),
'description' => 'Lists existing categories or tags with their IDs, so posts can be filed correctly. Call this before create-post to pick category IDs. Supports a search filter.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array(
'taxonomy' => array( 'type' => 'string', 'enum' => array( 'category', 'post_tag' ), 'default' => 'category' ),
'search' => array( 'type' => 'string', 'description' => 'Optional name filter.' ),
'limit' => array( 'type' => 'integer', 'minimum' => 1, 'maximum' => 200, 'default' => 100 ),
),
'additionalProperties' => false,
'default' => array(),
),
'output_schema' => array(
'type' => 'array',
'items' => array(
'type' => 'object',
'properties' => array(
'id' => array( 'type' => 'integer' ),
'name' => array( 'type' => 'string' ),
'slug' => array( 'type' => 'string' ),
'parent' => array( 'type' => 'integer' ),
'count' => array( 'type' => 'integer', 'description' => 'Published posts using the term.' ),
),
),
),
'execute_callback' => array( __CLASS__, 'list_terms' ),
'permission_callback' => function () {
return current_user_can( 'edit_posts' );
},
'meta' => self::meta( true, false, true ),
) );
wp_register_ability( 'agent-publisher/get-post', array(
'label' => __( 'Get a post', 'acadium-agent-publisher' ),
'description' => 'Returns a post or page you may edit (your own, or anyone\'s if the connected person\'s WordPress role allows it), in any status, including its raw content, categories and tags (posts), parent and template (pages), featured image with its generated sizes, and allowed custom fields. Use it before update-draft-post or update-published-post to see the current version; find IDs with find-posts.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array( 'id' => array( 'type' => 'integer', 'description' => 'Post ID.' ) ),
'required' => array( 'id' ),
'additionalProperties' => false,
),
'output_schema' => array(
'type' => 'object',
'properties' => array_merge( $post_output['properties'], $post_fields, array(
'categories' => array( 'type' => 'array', 'items' => array( 'type' => 'object' ) ),
'revisions' => array( 'type' => 'array', 'items' => array( 'type' => 'object' ), 'description' => 'Earlier versions, newest first (id, date, author). Undo a change with restore-revision.' ),
'content_is_live' => array( 'type' => 'boolean', 'description' => 'True if content is what visitors see. False if an active page builder draws this page from its own data: then content edits are refused.' ),
'page_builder' => array( 'type' => array( 'string', 'null' ), 'description' => 'Active page builder managing this page (e.g. beaver-builder), or null.' ),
'note' => array( 'type' => 'string', 'description' => 'How to edit this content.' ),
'modified' => array( 'type' => 'string' ),
'link' => array( 'type' => 'string' ),
) ),
),
'execute_callback' => array( __CLASS__, 'get_post' ),
'permission_callback' => function ( $input ) {
return self::can_read( $input['id'] ?? 0 );
},
'meta' => self::meta( true, false, true ),
) );
$image_source = array(
'url' => array( 'type' => 'string', 'description' => 'Public https URL of the image. Provide url OR data_base64.' ),
'data_base64' => array( 'type' => 'string', 'description' => 'Base64-encoded image bytes. Requires filename. Only practical for small files (under about 100 KB); for larger ones use url, or find-media for images the user uploaded. Never reduce an image\'s resolution to make it fit here: a featured image needs to be at least the width in get-capabilities > images. Whitespace and line breaks are ignored.' ),
'sha256' => array( 'type' => 'string', 'description' => 'Optional SHA-256 (hex) of the image file. If given, the upload is refused unless the received bytes match, so a copying mistake can\'t save a corrupted image.' ),
'filename' => array( 'type' => 'string', 'description' => 'File name with extension, e.g. hero.jpg.' ),
'alt_text' => array( 'type' => 'string', 'description' => 'Describe the image for screen readers. Required.' ),
'title' => array( 'type' => 'string' ),
'caption' => array( 'type' => 'string' ),
);
$edits = array(
'type' => 'array',
'description' => 'Change specific text without resending the whole content: each item replaces "find" (exact text copied from the current content with get-post, matching exactly once) with "replace". Use this for headlines, sentences, links or blocks in existing posts and pages; everything else stays exactly as it is. Don\'t combine with content.',
'items' => array(
'type' => 'object',
'properties' => array(
'find' => array( 'type' => 'string' ),
'replace' => array( 'type' => 'string' ),
),
'required' => array( 'find', 'replace' ),
'additionalProperties' => false,
),
);
$featured_image = array(
'type' => 'object',
'description' => 'Uploads an image and makes it the featured image (url is best: for a generic image use a stock photo URL; for the user\'s own image use request-upload, then featured_media). Use this or featured_media, not both. It must be at least the width in get-capabilities > images (recommended_width to look sharp); smaller images are refused when publishing unless the site allows them. Never shrink an image to fit through data_base64: ask the user to upload the full-size image (Media > Add New) and pass its id as featured_media (see find-media).',
'properties' => $image_source,
'required' => array( 'alt_text' ),
'additionalProperties' => false,
);
wp_register_ability( 'agent-publisher/create-post', array(
'label' => __( 'Create a post', 'acadium-agent-publisher' ),
'description' => 'Creates a new post or page (post_type "page") in one call: title, content, categories and tags (posts) or parent and template (pages), and optionally a featured image (featured_image uploads it for you). Pages need a role that can create pages (Editor or Administrator). status "draft" (default) saves it for a human to review; "pending" submits it for review; "publish" publishes it now, or schedules it when you pass a future date. Use "pending" or "publish" only when the site mode allows it (see agent-publisher/get-capabilities). When the user asked for the post to be published, pass status "publish" here instead of creating a draft and calling publish-post. For "publish", the site\'s pre-publish checks run first; if any fail, nothing is created and the error says what to fix, so you can correct the input and call again.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array_merge( array(
'post_type' => array( 'type' => 'string', 'enum' => $post_types, 'default' => $post_types[0] ),
), $post_fields, array(
'status' => array( 'type' => 'string', 'enum' => array( 'draft', 'pending', 'publish' ), 'default' => 'draft', 'description' => 'draft (default), pending (submit for review) or publish (publish now, or schedule with date).' ),
'date' => array( 'type' => 'string', 'description' => 'Only with status "publish": future publication time, ISO 8601 (e.g. 2026-10-01T09:00:00-04:00; without an offset the site\'s timezone is used). Omit to publish now.' ),
'featured_image' => $featured_image,
) ),
'required' => array( 'title', 'content' ),
'additionalProperties' => false,
),
'output_schema' => $publish_output,
'execute_callback' => array( __CLASS__, 'create_post' ),
'permission_callback' => function ( $input ) {
$status = $input['status'] ?? 'draft';
if ( 'pending' === $status && ! Agent_Publisher_Policy::allows( 'review' ) ) {
return Agent_Publisher_Policy::not_allowed( 'submit posts for review', 'review' );
}
if ( 'publish' === $status && ! Agent_Publisher_Policy::allows( 'publish' ) ) {
return Agent_Publisher_Policy::not_allowed( 'publish posts', 'publish' );
}
if ( ! empty( $input['featured_image'] ) && ! current_user_can( 'upload_files' ) ) {
return false;
}
$type = get_post_type_object( $input['post_type'] ?? self::post_types()[0] );
if ( ! $type || ! current_user_can( $type->cap->edit_posts ) ) {
return new WP_Error( 'agent_publisher_role', sprintf( 'Your WordPress role can\'t create %s.', $type ? strtolower( $type->labels->name ) : 'this type' ), array( 'status' => 403 ) );
}
// People publish only if their own role lets them (AI Agent users: the mode decides).
if ( 'publish' === $status && ! Agent_Publisher_Policy::can_publish( $type ) ) {
return new WP_Error( 'agent_publisher_role', 'Your WordPress role can\'t publish posts, so Claude can\'t publish them for you. Create a draft or submit it for review instead.', array( 'status' => 403 ) );
}
return true;
},
'meta' => self::meta( false, false, false ),
) );
wp_register_ability( 'agent-publisher/update-draft-post', array(
'label' => __( 'Update a draft post', 'acadium-agent-publisher' ),
'description' => 'Changes fields of a post or page that is still a draft or pending review: your own, or anyone\'s if the connected person\'s role allows editing others\' content (the original author is kept). Only the fields you pass are changed. Published and scheduled posts are refused: use update-published-post if the site allows it, or unpublish-post first.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array_merge( array(
'id' => array( 'type' => 'integer', 'description' => 'ID of the draft to change.' ),
), $post_fields, array( 'featured_image' => $featured_image, 'edits' => $edits ) ),
'required' => array( 'id' ),
'additionalProperties' => false,
),
'output_schema' => $post_output,
'execute_callback' => array( __CLASS__, 'update_draft' ),
'permission_callback' => function ( $input ) {
if ( ! empty( $input['featured_image'] ) && ! current_user_can( 'upload_files' ) ) {
return false;
}
return self::can_edit( $input['id'] ?? 0 );
},
'meta' => self::meta( false, true, false ),
) );
wp_register_ability( 'agent-publisher/submit-for-review', array(
'label' => __( 'Submit a draft for review', 'acadium-agent-publisher' ),
'description' => 'Moves one of your drafts to "Pending review" so a site editor can review and publish it. Only when the site mode allows review (see agent-publisher/get-capabilities).',
'category' => self::CATEGORY,
'input_schema' => $id_only,
'output_schema' => $post_output,
'execute_callback' => array( __CLASS__, 'submit_for_review' ),
'permission_callback' => function ( $input ) {
if ( ! Agent_Publisher_Policy::allows( 'review' ) ) {
return Agent_Publisher_Policy::not_allowed( 'submit posts for review', 'review' );
}
return self::can_manage( $input['id'] ?? 0 );
},
'meta' => self::meta( false, false, true ),
) );
wp_register_ability( 'agent-publisher/publish-post', array(
'label' => __( 'Publish or schedule a post', 'acadium-agent-publisher' ),
'description' => 'Publishes one of your existing drafts (or pending/scheduled posts) now, or schedules it when you pass a future date. For a new post, use create-post with status "publish" instead. Publishing is visible to site visitors: go ahead when the user asked you to publish; otherwise ask them first. The site\'s pre-publish checks run first (see agent-publisher/get-capabilities); if any fail, nothing changes and the error says what to fix. Only when the site mode allows publishing.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array(
'id' => array( 'type' => 'integer', 'description' => 'Post ID.' ),
'date' => array( 'type' => 'string', 'description' => 'Optional future publication time, ISO 8601 (e.g. 2026-10-01T09:00:00-04:00; without an offset the site\'s timezone is used). Omit to publish now.' ),
),
'required' => array( 'id' ),
'additionalProperties' => false,
),
'output_schema' => $publish_output,
'execute_callback' => array( __CLASS__, 'publish_post' ),
'permission_callback' => function ( $input ) {
if ( ! Agent_Publisher_Policy::allows( 'publish' ) ) {
return Agent_Publisher_Policy::not_allowed( 'publish posts', 'publish' );
}
$ok = self::can_manage( $input['id'] ?? 0 );
if ( true !== $ok ) {
return $ok;
}
return Agent_Publisher_Policy::can_publish( get_post_type_object( get_post_type( (int) $input['id'] ) ) )
? true
: new WP_Error( 'agent_publisher_role', 'Your WordPress role can\'t publish posts, so Claude can\'t publish them for you.', array( 'status' => 403 ) );
},
'meta' => self::meta( false, true, false ),
) );
wp_register_ability( 'agent-publisher/unpublish-post', array(
'label' => __( 'Unpublish a post', 'acadium-agent-publisher' ),
'description' => 'Takes one of your published or scheduled posts offline by switching it back to draft (content is kept; it can be published again). Use it to undo a publish. Only when the site mode allows publishing.',
'category' => self::CATEGORY,
'input_schema' => $id_only,
'output_schema' => $post_output,
'execute_callback' => array( __CLASS__, 'unpublish_post' ),
'permission_callback' => function ( $input ) {
if ( ! Agent_Publisher_Policy::allows( 'publish' ) ) {
return Agent_Publisher_Policy::not_allowed( 'unpublish posts', 'publish' );
}
$ok = self::can_manage( $input['id'] ?? 0 );
if ( true !== $ok ) {
return $ok;
}
return Agent_Publisher_Policy::can_publish( get_post_type_object( get_post_type( (int) $input['id'] ) ) )
? true
: new WP_Error( 'agent_publisher_role', 'Your WordPress role can\'t publish or unpublish posts.', array( 'status' => 403 ) );
},
'meta' => self::meta( false, true, false ),
) );
wp_register_ability( 'agent-publisher/update-published-post', array(
'label' => __( 'Update a published post', 'acadium-agent-publisher' ),
'description' => 'Changes fields of a post or page that is already live (yours, or anyone\'s if the connected person\'s role allows it; the original author is kept and WordPress keeps the previous version as a revision), including replacing its featured image in one step (featured_image uploads a new one; featured_media uses one from the Media Library). Only the fields you pass are changed, and visitors see the change immediately: go ahead when the user asked for the change; otherwise ask them first. Only when the site mode is "Publish and edit live posts". Use get-post first to see the current version.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array_merge( array(
'id' => array( 'type' => 'integer', 'description' => 'ID of the published post to change.' ),
), $post_fields, array( 'featured_image' => $featured_image, 'edits' => $edits ) ),
'required' => array( 'id' ),
'additionalProperties' => false,
),
'output_schema' => $publish_output,
'execute_callback' => array( __CLASS__, 'update_published' ),
'permission_callback' => function ( $input ) {
if ( ! Agent_Publisher_Policy::allows( 'publish_edit' ) ) {
return Agent_Publisher_Policy::not_allowed( 'edit published posts', 'publish_edit' );
}
if ( ! empty( $input['featured_image'] ) && ! current_user_can( 'upload_files' ) ) {
return false;
}
$ok = self::can_manage( $input['id'] ?? 0 );
if ( true !== $ok ) {
return $ok;
}
return Agent_Publisher_Policy::can_edit_published( get_post_type_object( get_post_type( (int) $input['id'] ) ) )
? true
: new WP_Error( 'agent_publisher_role', 'Your WordPress role can\'t edit published posts.', array( 'status' => 403 ) );
},
'meta' => self::meta( false, true, false ),
) );
wp_register_ability( 'agent-publisher/upload-media', array(
'label' => __( 'Upload an image', 'acadium-agent-publisher' ),
'description' => 'For a generic or illustrative image (the user did not supply or describe a specific picture), use a free stock photo: pass its direct https image URL (e.g. from Unsplash, Pexels or Wikimedia Commons; respect the license and credit the photographer in the post if it asks for that). Don\'t generate an image and send it as data_base64 unless the user asks for a custom graphic: it is slow and limited to small files. For the user\'s own image, call request-upload and give them the link. Adds an image to the Media Library from a public https URL or from base64 data, with alt text, and returns its ID, URL and generated sizes to use in post content (). For a featured image, use featured_image on create-post / update-draft-post / update-published-post instead. base64 is only practical for small images: for large ones use a public url, or ask the user to upload the image in WordPress (Media > Add New) and find it with find-media. Optionally attaches the image to an existing draft and makes it that draft\'s featured image.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array_merge( $image_source, array(
'post_id' => array( 'type' => 'integer', 'description' => 'Optional draft to attach the image to.' ),
'set_featured' => array( 'type' => 'boolean', 'default' => false, 'description' => 'Make it the featured image of post_id.' ),
) ),
'required' => array( 'alt_text' ),
'additionalProperties' => false,
),
'output_schema' => array(
'type' => 'object',
'properties' => array(
'id' => array( 'type' => 'integer' ),
'url' => array( 'type' => 'string' ),
'width' => array( 'type' => 'integer' ),
'height' => array( 'type' => 'integer' ),
'alt' => array( 'type' => 'string' ),
'sizes' => array( 'type' => 'object' ),
'mime' => array( 'type' => 'string' ),
'bytes' => array( 'type' => 'integer', 'description' => 'Size of the uploaded file.' ),
'sha256' => array( 'type' => 'string', 'description' => 'SHA-256 of the uploaded file, to compare with the original.' ),
'warnings' => array( 'type' => 'array', 'items' => array( 'type' => 'string' ), 'description' => 'Problems if this image is used as a featured image on this site.' ),
),
),
'execute_callback' => array( __CLASS__, 'upload_media' ),
'permission_callback' => function ( $input ) {
if ( ! current_user_can( 'upload_files' ) ) {
return false;
}
if ( ! empty( $input['post_id'] ) ) {
return self::can_edit( $input['post_id'] );
}
return true;
},
'meta' => self::meta( false, false, false ),
) );
wp_register_ability( 'agent-publisher/request-upload', array(
'label' => __( 'Ask the user to upload an image', 'acadium-agent-publisher' ),
'description' => 'Creates a one-time upload link (valid 30 minutes) for the user\'s own image: a photo they have, or any image too large to send as data_base64. Give the user the upload_url and ask them to open it and drop the image in; it goes into the Media Library under their name, at full size. Then call get-upload with the upload_id to get the image and use its id as featured_media (or its url in content). Use a stock photo URL instead when any generic image will do.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array(
'alt_text' => array( 'type' => 'string', 'description' => 'Suggested description of the image (the user can change it on the upload page).' ),
),
'additionalProperties' => false,
'default' => array(),
),
'output_schema' => array(
'type' => 'object',
'properties' => array(
'upload_id' => array( 'type' => 'string' ),
'upload_url' => array( 'type' => 'string', 'description' => 'Give this link to the user.' ),
'expires_at' => array( 'type' => 'string' ),
'max_bytes' => array( 'type' => 'integer' ),
),
),
'execute_callback' => function ( $input = array() ) {
return Agent_Publisher_Upload_Link::create( $input['alt_text'] ?? '' );
},
'permission_callback' => function () {
return current_user_can( 'upload_files' )
? true
: new WP_Error( 'agent_publisher_role', 'Your WordPress role can\'t upload files, so Claude can\'t add images for you. Ask a site administrator for a role that can (Author or above).', array( 'status' => 403 ) );
},
'meta' => self::meta( false, false, false ),
) );
wp_register_ability( 'agent-publisher/get-upload', array(
'label' => __( 'Check an upload link', 'acadium-agent-publisher' ),
'description' => 'Returns the status of an upload link from request-upload: "pending" (the user hasn\'t uploaded yet), "expired", or "done" with the image (id, url, size, generated sizes, warnings). Call it after the user says they uploaded the image.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array( 'upload_id' => array( 'type' => 'string' ) ),
'required' => array( 'upload_id' ),
'additionalProperties' => false,
),
'output_schema' => array(
'type' => 'object',
'properties' => array(
'status' => array( 'type' => 'string', 'enum' => array( 'pending', 'expired', 'done' ) ),
'image' => array( 'type' => 'object' ),
),
),
'execute_callback' => function ( $input ) {
return Agent_Publisher_Upload_Link::status( $input['upload_id'] );
},
'permission_callback' => function () {
return current_user_can( 'upload_files' );
},
'meta' => self::meta( true, false, true ),
) );
wp_register_ability( 'agent-publisher/trash-post', array(
'label' => __( 'Move a post or page to the Trash', 'acadium-agent-publisher' ),
'description' => 'Moves a post or page to the Trash, if the connected person\'s WordPress role may delete it (Editors and Administrators: anyone\'s; Authors: their own posts; Contributors: their own unpublished drafts). It is not deleted permanently: it can be restored from the Trash in WordPress for 30 days. Published content also needs the site mode "Publish" or above. Confirm with the user which item you mean before trashing.',
'category' => self::CATEGORY,
'input_schema' => $id_only,
'output_schema' => array(
'type' => 'object',
'properties' => array(
'id' => array( 'type' => 'integer' ),
'type' => array( 'type' => 'string' ),
'title' => array( 'type' => 'string' ),
'status' => array( 'type' => 'string' ),
'restore_url' => array( 'type' => 'string', 'description' => 'Where a person can restore it in wp-admin.' ),
),
),
'execute_callback' => array( __CLASS__, 'trash_post' ),
'permission_callback' => function ( $input ) {
$post = get_post( (int) ( $input['id'] ?? 0 ) );
if ( ! $post || ! in_array( $post->post_type, self::post_types(), true ) || 'trash' === $post->post_status ) {
return new WP_Error( 'agent_publisher_not_found', 'No such post (or it is already in the Trash).', array( 'status' => 404 ) );
}
if ( in_array( $post->post_status, array( 'publish', 'future', 'private' ), true ) && ! Agent_Publisher_Policy::allows( 'publish' ) ) {
return Agent_Publisher_Policy::not_allowed( 'move published content to the Trash', 'publish' );
}
if ( Agent_Publisher_Policy::is_agent_user() ) {
return (int) $post->post_author === get_current_user_id() ? true : new WP_Error( 'agent_publisher_not_yours', 'You can only trash your own posts.', array( 'status' => 403 ) );
}
return current_user_can( 'delete_post', $post->ID ) ? true : new WP_Error( 'agent_publisher_role', 'Your WordPress role can\'t delete this, so Claude can\'t move it to the Trash for you.', array( 'status' => 403 ) );
},
'meta' => self::meta( false, true, false ),
) );
wp_register_ability( 'agent-publisher/restore-revision', array(
'label' => __( 'Restore an earlier version', 'acadium-agent-publisher' ),
'description' => 'Restores a post or page to one of its earlier versions (get-post > revisions), exactly as it was stored, markup included. Use it to undo a change. The version being replaced is kept as a revision too. Live content needs the site mode "Publish and edit live posts".',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array(
'id' => array( 'type' => 'integer', 'description' => 'Post or page ID.' ),
'revision_id' => array( 'type' => 'integer', 'description' => 'Revision ID from get-post > revisions.' ),
),
'required' => array( 'id', 'revision_id' ),
'additionalProperties' => false,
),
'output_schema' => $publish_output,
'execute_callback' => array( __CLASS__, 'restore_revision' ),
'permission_callback' => function ( $input ) {
$post = get_post( (int) ( $input['id'] ?? 0 ) );
if ( $post && ! in_array( $post->post_status, self::EDITABLE_STATUSES, true ) ) {
if ( ! Agent_Publisher_Policy::allows( 'publish_edit' ) ) {
return Agent_Publisher_Policy::not_allowed( 'change published content', 'publish_edit' );
}
$ok = self::can_manage( $post->ID );
if ( true !== $ok ) {
return $ok;
}
return Agent_Publisher_Policy::can_edit_published( get_post_type_object( $post->post_type ) )
? true
: new WP_Error( 'agent_publisher_role', 'Your WordPress role can\'t edit published content.', array( 'status' => 403 ) );
}
return self::can_edit( $input['id'] ?? 0 );
},
'meta' => self::meta( false, true, false ),
) );
wp_register_ability( 'agent-publisher/find-posts', array(
'label' => __( 'Find posts and pages', 'acadium-agent-publisher' ),
'description' => 'Searches existing posts and pages you may read or edit, newest change first: by words in the title or content, type, status, or only your own. Returns ids to use with get-post, update-draft-post and update-published-post. Use it when the user asks to change an existing post or page.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array(
'search' => array( 'type' => 'string', 'description' => 'Words from the title or content. Omit to list recent ones.' ),
'post_type' => array( 'type' => 'string', 'enum' => array_merge( array( 'any' ), $post_types ), 'default' => 'any' ),
'status' => array( 'type' => 'string', 'enum' => array( 'any', 'publish', 'draft', 'pending', 'future', 'private' ), 'default' => 'any' ),
'mine' => array( 'type' => 'boolean', 'default' => false, 'description' => 'Only content the connected person authored.' ),
'limit' => array( 'type' => 'integer', 'minimum' => 1, 'maximum' => 50, 'default' => 20 ),
),
'additionalProperties' => false,
'default' => array(),
),
'output_schema' => array(
'type' => 'array',
'items' => array(
'type' => 'object',
'properties' => array(
'id' => array( 'type' => 'integer' ),
'type' => array( 'type' => 'string' ),
'status' => array( 'type' => 'string' ),
'title' => array( 'type' => 'string' ),
'author' => array( 'type' => 'string' ),
'modified' => array( 'type' => 'string' ),
'link' => array( 'type' => 'string' ),
'parent' => array( 'type' => 'integer' ),
'can_edit' => array( 'type' => 'boolean', 'description' => 'Whether you may change it (drafts: update-draft-post; published: update-published-post, if the site mode allows).' ),
'page_builder' => array( 'type' => array( 'string', 'null' ), 'description' => 'An active page builder that draws this page from its own data (its content can\'t be edited here), or null.' ),
),
),
),
'execute_callback' => array( __CLASS__, 'find_posts' ),
'permission_callback' => function () {
return current_user_can( 'edit_posts' ) || current_user_can( 'edit_pages' );
},
'meta' => self::meta( true, false, true ),
) );
wp_register_ability( 'agent-publisher/find-media', array(
'label' => __( 'Find images in the Media Library', 'acadium-agent-publisher' ),
'description' => 'Searches the Media Library for images by title or file name, newest first, e.g. images the user uploaded in WordPress. Use a result\'s id as featured_media, or its url in post content. This is the best way to use large or high-resolution images: ask the user to upload them under Media > Add New, then find them here.',
'category' => self::CATEGORY,
'input_schema' => array(
'type' => 'object',
'properties' => array(
'search' => array( 'type' => 'string', 'description' => 'Words from the image title or file name. Omit to list the newest images.' ),
'mine' => array( 'type' => 'boolean', 'default' => false, 'description' => 'Only images you uploaded.' ),
'limit' => array( 'type' => 'integer', 'minimum' => 1, 'maximum' => 50, 'default' => 20 ),
),
'additionalProperties' => false,
'default' => array(),
),
'output_schema' => array(
'type' => 'array',
'items' => array(
'type' => 'object',
'properties' => array(
'id' => array( 'type' => 'integer' ),
'title' => array( 'type' => 'string' ),
'filename' => array( 'type' => 'string' ),
'url' => array( 'type' => 'string' ),
'width' => array( 'type' => 'integer' ),
'height' => array( 'type' => 'integer' ),
'alt' => array( 'type' => 'string' ),
'mime' => array( 'type' => 'string' ),
'date' => array( 'type' => 'string' ),
'uploaded_by' => array( 'type' => 'string' ),
'attached_to' => array( 'type' => 'integer', 'description' => 'Post the image was uploaded to (0 if none).' ),
'warnings' => array( 'type' => 'array', 'items' => array( 'type' => 'string' ), 'description' => 'Problems if used as a featured image on this site.' ),
),
),
),
'execute_callback' => array( __CLASS__, 'find_media' ),
'permission_callback' => function () {
return current_user_can( 'upload_files' );
},
'meta' => self::meta( true, false, true ),
) );
}
/* ------------------------------------------------------------------ */
/* Configuration */
/* ------------------------------------------------------------------ */
private static function post_types() {
$types = array_values( array_filter( (array) apply_filters( 'agent_publisher_post_types', array( 'post', 'page', 'wp_block' ) ), 'post_type_exists' ) );
return $types ? $types : array( 'post' );
}
private static function max_upload() {
return (int) apply_filters( 'agent_publisher_max_upload', 10 * MB_IN_BYTES );
}
public static function upload_mimes() {
return (array) apply_filters( 'agent_publisher_upload_mimes', array(
'jpg|jpeg|jpe' => 'image/jpeg',
'png' => 'image/png',
'gif' => 'image/gif',
'webp' => 'image/webp',
) );
}
private static function meta_keys() {
return array_values( array_filter( (array) apply_filters( 'agent_publisher_post_meta', array() ), 'is_string' ) );
}
/** The user may edit this post, it is a supported type, and it is not published. */
private static function can_edit( $id ) {
$post = get_post( (int) $id );
if ( ! $post || ! in_array( $post->post_type, self::post_types(), true ) ) {
return new WP_Error( 'agent_publisher_not_found', 'No such post.', array( 'status' => 404 ) );
}
if ( current_user_can( 'edit_post', $post->ID ) ) {
return true;
}
if ( in_array( $post->post_status, array( 'publish', 'future' ), true ) && (int) $post->post_author === get_current_user_id() ) {
return new WP_Error(
'agent_publisher_not_a_draft',
sprintf( 'Post %d is "%s". Use update-published-post (if the site allows it) or unpublish-post first; see agent-publisher/get-capabilities.', $post->ID, $post->post_status ),
array( 'status' => 409 )
);
}
return false;
}
/**
* The user may read this post in any status: an AI Agent user its own
* posts (the role can't edit published posts, but may read them);
* anyone else what WordPress lets them edit.
*/
private static function can_read( $id ) {
$post = get_post( (int) $id );
if ( ! $post || ! in_array( $post->post_type, self::post_types(), true ) ) {
return new WP_Error( 'agent_publisher_not_found', 'No such post.', array( 'status' => 404 ) );
}
if ( current_user_can( 'edit_post', $post->ID ) || ( Agent_Publisher_Policy::acting_for_agent() && (int) $post->post_author === get_current_user_id() ) ) {
return true;
}
return new WP_Error( 'agent_publisher_not_yours', Agent_Publisher_Policy::is_agent_user() ? 'You can only read your own posts.' : 'Your WordPress role doesn\'t let you edit this, so Claude can\'t read or change it for you.', array( 'status' => 403 ) );
}
/**
* The post exists, is a supported type, and the current user may change
* its status: an AI Agent user its own posts (the role has no capability
* for published posts, so ownership is checked here and the site mode by
* each ability); anyone else only what WordPress lets them edit.
*/
private static function can_manage( $id ) {
$post = get_post( (int) $id );
if ( ! $post || ! in_array( $post->post_type, self::post_types(), true ) ) {
return new WP_Error( 'agent_publisher_not_found', 'No such post.', array( 'status' => 404 ) );
}
// AI Agent users: only what they created. People: what their own role may edit
// (capped to content rights through a connection; see Agent_Publisher_OAuth_Server::cap_connection()).
if ( Agent_Publisher_Policy::is_agent_user() ? (int) $post->post_author === get_current_user_id() : current_user_can( 'edit_post', $post->ID ) ) {
return true;
}
return new WP_Error( 'agent_publisher_not_yours', Agent_Publisher_Policy::is_agent_user() ? 'You can only change your own posts.' : 'Your WordPress role doesn\'t let you edit this, so Claude can\'t change it for you.', array( 'status' => 403 ) );
}
/* ------------------------------------------------------------------ */
/* Callbacks */
/* ------------------------------------------------------------------ */
public static function get_capabilities() {
$s = Agent_Publisher_Policy::settings();
$user = wp_get_current_user();
$type = get_post_type_object( self::post_types()[0] );
$names = array();
foreach ( $s['allowed_categories'] as $id ) {
$term = get_term( $id, 'category' );
if ( $term && ! is_wp_error( $term ) ) {
$names[] = array( 'id' => (int) $id, 'name' => html_entity_decode( $term->name ) );
}
}
return array(
'mode' => $s['mode'],
'mode_label' => Agent_Publisher_Policy::mode_labels()[ $s['mode'] ],
'allowed' => array(
'create_drafts' => true,
'update_drafts' => true,
'upload_media' => current_user_can( 'upload_files' ),
'submit_for_review' => Agent_Publisher_Policy::allows( 'review' ),
'publish' => Agent_Publisher_Policy::allows( 'publish' ) && Agent_Publisher_Policy::can_publish( $type ),
'schedule' => Agent_Publisher_Policy::allows( 'publish' ) && Agent_Publisher_Policy::can_publish( $type ),
'unpublish' => Agent_Publisher_Policy::allows( 'publish' ) && Agent_Publisher_Policy::can_publish( $type ),
'edit_published' => Agent_Publisher_Policy::allows( 'publish_edit' ) && Agent_Publisher_Policy::can_edit_published( $type ),
),
'checks' => array(
'require_featured_image' => (bool) $s['require_featured_image'],
'allowed_categories' => $names,
'daily_limit' => (int) $s['daily_limit'],
'published_last_24h' => Agent_Publisher_Policy::published_last_24h(),
'strict_image_checks' => (bool) $s['image_checks_strict'],
),
'content_types' => self::content_types_info(),
'page_builders_active' => array_keys( array_filter( self::page_builders(), function ( $b ) {
return $b[1];
} ) ),
'images' => array(
'how_to_add' => 'For a generic or illustrative image (the user did not supply or describe a specific picture), use a free stock photo: pass its direct https image URL (e.g. from Unsplash, Pexels or Wikimedia Commons; respect the license and credit the photographer in the post if it asks for that). Don\'t generate an image and send it as data_base64 unless the user asks for a custom graphic: it is slow and limited to small files. For the user\'s own image, call request-upload and give them the link. Prefer a public https url, or find-media for images already in the Media Library. data_base64 is only practical for small images (under about 100 KB); pass sha256 of the file to verify it arrived intact. Never reduce an image\'s resolution to make it fit through data_base64: if a full-size image is too large to send, ask the user to upload it (Media > Add New) and use find-media.',
'accepted_types' => array_values( self::upload_mimes() ),
'max_upload_bytes' => self::max_upload(),
'scaled_down_above_px' => (int) apply_filters( 'big_image_size_threshold', 2560, array( 0, 0 ), '', 0 ), // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- core filter.
'generated_sizes' => wp_get_registered_image_subsizes(),
'featured_image' => array(
'min_width' => Agent_Publisher_Policy::min_image_width(),
'min_width_source' => $s['image_min_width'] ? 'site setting' : 'default',
'recommended_width' => Agent_Publisher_Policy::recommended_image_width(),
'small_blocks_publishing' => $s['image_checks_strict'] || $s['image_block_small'],
'aspect_ratios' => array_keys( Agent_Publisher_Policy::aspect_ratios() ),
'guidance' => $s['image_guidance'],
),
),
'user' => array(
'id' => (int) $user->ID,
'name' => $user->display_name,
'roles' => array_values( $user->roles ),
'unfiltered_html' => current_user_can( 'unfiltered_html' ),
'posts_credit' => 'Posts you create are credited to ' . $user->display_name . ' and owned by them' . ( Agent_Publisher_Policy::is_agent_user() ? ' (an AI Agent user).' : ': they can edit them in WordPress.' ),
),
);
}
public static function list_terms( $input = array() ) {
$terms = get_terms( array(
'taxonomy' => $input['taxonomy'] ?? 'category',
'hide_empty' => false,
'search' => $input['search'] ?? '',
'number' => $input['limit'] ?? 100,
'orderby' => 'count',
'order' => 'DESC',
) );
if ( is_wp_error( $terms ) ) {
return $terms;
}
return array_map( function ( $t ) {
return array(
'id' => (int) $t->term_id,
'name' => html_entity_decode( $t->name ),
'slug' => $t->slug,
'parent' => (int) $t->parent,
'count' => (int) $t->count,
);
}, $terms );
}
public static function get_post( $input ) {
$post = get_post( (int) $input['id'] );
$out = self::summary( $post );
$out += array(
'content' => $post->post_content,
'excerpt' => $post->post_excerpt,
'slug' => $post->post_name,
'categories' => array_map( function ( $t ) {
return array( 'id' => (int) $t->term_id, 'name' => html_entity_decode( $t->name ) );
}, get_the_category( $post->ID ) ),
'tags' => wp_list_pluck( (array) get_the_tags( $post->ID ), 'name' ),
'featured_media' => (int) get_post_thumbnail_id( $post ),
'parent' => (int) $post->post_parent,
'menu_order' => (int) $post->menu_order,
'template' => (string) ( get_page_template_slug( $post ) ?: 'default' ),
'revisions' => array_values( array_map( function ( $r ) {
return array(
'id' => (int) $r->ID,
'date' => mysql2date( 'c', $r->post_modified, false ),
'author' => (string) get_the_author_meta( 'display_name', (int) $r->post_author ),
);
}, wp_get_post_revisions( $post->ID, array( 'posts_per_page' => 10, 'check_enabled' => false ) ) ) ),
) + self::builder_status( $post ) + array(
'meta' => (object) array_map( function ( $key ) use ( $post ) {
return (string) get_post_meta( $post->ID, $key, true );
}, array_combine( self::meta_keys(), self::meta_keys() ) ?: array() ),
// Drafts have no GMT modified date; the local one is always set.
'modified' => mysql2date( 'c', $post->post_modified, false ),
'link' => get_permalink( $post ),
);
return $out;
}
public static function create_post( $input ) {
$status = $input['status'] ?? 'draft';
if ( ! empty( $input['date'] ) && 'publish' !== $status ) {
return new WP_Error( 'agent_publisher_date_needs_publish', 'date is only used with status "publish".', array( 'status' => 400 ) );
}
if ( ! empty( $input['featured_image'] ) && isset( $input['featured_media'] ) ) {
return new WP_Error( 'agent_publisher_two_images', 'Pass featured_image or featured_media, not both.', array( 'status' => 400 ) );
}
$valid = self::validate_extras( $input );
if ( true === $valid ) {
$valid = self::validate_type_fields( $input['post_type'] ?? self::post_types()[0], $input );
}
if ( is_wp_error( $valid ) ) {
return $valid;
}
$dates = null;
if ( 'publish' === $status ) {
$dates = self::publish_dates( $input['date'] ?? '' );
if ( is_wp_error( $dates ) ) {
return $dates;
}
}
// Upload first, so a failed download leaves nothing behind.
$uploaded = 0;
if ( ! empty( $input['featured_image'] ) ) {
$uploaded = self::sideload_image( $input['featured_image'], 0 );
if ( is_wp_error( $uploaded ) ) {
return $uploaded;
}
}
$image = $uploaded ? $uploaded : (int) ( $input['featured_media'] ?? 0 );
$postarr = self::postarr( $input );
$postarr['post_type'] = $input['post_type'] ?? self::post_types()[0];
$postarr['post_status'] = 'pending' === $status ? 'pending' : 'draft';
$postarr['post_author'] = get_current_user_id();
if ( isset( $input['categories'] ) ) {
$postarr['post_category'] = array_map( 'intval', $input['categories'] );
}
$id = wp_insert_post( wp_slash( $postarr ), true );
if ( is_wp_error( $id ) ) {
if ( $uploaded ) {
wp_delete_attachment( $uploaded, true );
}
return $id;
}
if ( $uploaded ) {
wp_update_post( array( 'ID' => $uploaded, 'post_parent' => $id ) );
}
if ( $image ) {
set_post_thumbnail( $id, $image );
}
if ( 'publish' === $status ) {
$checks = Agent_Publisher_Policy::check_publishable( get_post( $id ) );
if ( is_wp_error( $checks ) ) {
// Undo, so the agent can fix its input and call again without leaving a stray draft.
wp_delete_post( $id, true );
if ( $uploaded ) {
wp_delete_attachment( $uploaded, true );
}
return new WP_Error(
$checks->get_error_code(),
str_replace( 'The post was left unchanged.', 'Nothing was created.', $checks->get_error_message() ),
$checks->get_error_data()
);
}
}
self::save_extras( $id, $input );
Agent_Publisher_Policy::log( 'create', $id );
if ( $uploaded ) {
Agent_Publisher_Policy::log( 'upload', $id, wp_get_attachment_url( $uploaded ) );
}
if ( 'pending' === $status ) {
Agent_Publisher_Policy::log( 'submit', $id );
}
if ( 'publish' === $status ) {
return self::apply_publish( get_post( $id ), $dates );
}
return self::summary( get_post( $id ) );
}
public static function update_draft( $input ) {
$post = get_post( (int) $input['id'] );
if ( ! in_array( $post->post_status, self::EDITABLE_STATUSES, true ) ) {
return new WP_Error(
'agent_publisher_not_a_draft',
sprintf( 'Post %d is "%s". Only drafts can be changed; ask a human to switch it back to draft in WordPress first.', $post->ID, $post->post_status ),
array( 'status' => 409 )
);
}
$valid = self::validate_extras( $input );
if ( true === $valid ) {
$valid = self::validate_type_fields( $post->post_type, $input, $post->ID );
}
if ( is_wp_error( $valid ) ) {
return $valid;
}
$prepared = self::prepare_content( $post, $input );
if ( is_wp_error( $prepared ) ) {
return $prepared;
}
list( $input, $raw ) = $prepared;
$builder = self::refuse_builder_content( $post, $input );
if ( is_wp_error( $builder ) ) {
return $builder;
}
// Upload first: if it fails, nothing is changed.
$uploaded = self::upload_featured( $input, $post->ID );
if ( is_wp_error( $uploaded ) ) {
return $uploaded;
}
$postarr = self::postarr( $input );
$postarr['ID'] = $post->ID;
if ( count( $postarr ) > 1 ) {
$id = self::update_post( $postarr, $raw );
if ( is_wp_error( $id ) ) {
if ( $uploaded ) {
wp_delete_attachment( $uploaded, true );
}
return $id;
}
}
self::save_extras( $post->ID, $input );
if ( $uploaded ) {
set_post_thumbnail( $post->ID, $uploaded );
Agent_Publisher_Policy::log( 'upload', $post->ID, wp_get_attachment_url( $uploaded ) );
}
Agent_Publisher_Policy::log( 'update', $post->ID );
return self::summary( get_post( $post->ID ) );
}
public static function submit_for_review( $input ) {
$post = get_post( (int) $input['id'] );
if ( 'pending' === $post->post_status ) {
return self::summary( $post );
}
if ( ! in_array( $post->post_status, array( 'draft', 'auto-draft' ), true ) ) {
return new WP_Error( 'agent_publisher_not_a_draft', sprintf( 'Post %d is "%s"; only drafts can be submitted for review.', $post->ID, $post->post_status ), array( 'status' => 409 ) );
}
$id = wp_update_post( array( 'ID' => $post->ID, 'post_status' => 'pending' ), true );
if ( is_wp_error( $id ) ) {
return $id;
}
Agent_Publisher_Policy::log( 'submit', $post->ID );
return self::summary( get_post( $post->ID ) );
}
public static function publish_post( $input ) {
$post = get_post( (int) $input['id'] );
if ( 'publish' === $post->post_status ) {
return new WP_Error( 'agent_publisher_already_published', sprintf( 'Post %d is already published: %s', $post->ID, get_permalink( $post ) ), array( 'status' => 409 ) );
}
if ( ! in_array( $post->post_status, array( 'draft', 'pending', 'auto-draft', 'future' ), true ) ) {
return new WP_Error( 'agent_publisher_bad_status', sprintf( 'Post %d is "%s" and cannot be published by an agent.', $post->ID, $post->post_status ), array( 'status' => 409 ) );
}
$dates = self::publish_dates( $input['date'] ?? '' );
if ( is_wp_error( $dates ) ) {
return $dates;
}
// Rescheduling an already scheduled post doesn't count toward the daily limit again.
$checks = Agent_Publisher_Policy::check_publishable( $post, 'future' !== $post->post_status );
if ( is_wp_error( $checks ) ) {
return $checks;
}
return self::apply_publish( $post, $dates );
}
/** [ local, gmt ] publication dates: now, or a future ISO 8601 time. */
private static function publish_dates( $date ) {
if ( '' === (string) $date ) {
return array( current_time( 'mysql' ), current_time( 'mysql', true ) );
}
$dates = rest_get_date_with_gmt( $date );
if ( ! $dates ) {
return new WP_Error( 'agent_publisher_bad_date', 'date must be ISO 8601, e.g. 2026-10-01T09:00:00-04:00.', array( 'status' => 400 ) );
}
if ( strtotime( $dates[1] . ' UTC' ) <= time() + MINUTE_IN_SECONDS ) {
return new WP_Error( 'agent_publisher_past_date', 'date must be in the future. Omit it to publish now.', array( 'status' => 400 ) );
}
return $dates;
}
/** Publish (or schedule, for a future date) a post that passed the pre-publish checks. */
private static function apply_publish( $post, $dates ) {
$id = wp_update_post( array(
'ID' => $post->ID,
'post_status' => 'publish',
'edit_date' => true,
'post_date' => $dates[0],
'post_date_gmt' => $dates[1],
), true );
if ( is_wp_error( $id ) ) {
return $id;
}
$post = get_post( $post->ID );
Agent_Publisher_Policy::log( 'future' === $post->post_status ? 'schedule' : 'publish', $post->ID, 'future' === $post->post_status ? $post->post_date : '' );
return self::published_summary( $post );
}
public static function unpublish_post( $input ) {
$post = get_post( (int) $input['id'] );
if ( ! in_array( $post->post_status, array( 'publish', 'future' ), true ) ) {
return new WP_Error( 'agent_publisher_not_published', sprintf( 'Post %d is "%s", not published or scheduled.', $post->ID, $post->post_status ), array( 'status' => 409 ) );
}
$id = wp_update_post( array( 'ID' => $post->ID, 'post_status' => 'draft' ), true );
if ( is_wp_error( $id ) ) {
return $id;
}
Agent_Publisher_Policy::log( 'unpublish', $post->ID );
return self::summary( get_post( $post->ID ) );
}
public static function update_published( $input ) {
$post = get_post( (int) $input['id'] );
if ( 'publish' !== $post->post_status ) {
return new WP_Error( 'agent_publisher_not_published', sprintf( 'Post %d is "%s"; use update-draft-post for unpublished posts.', $post->ID, $post->post_status ), array( 'status' => 409 ) );
}
$prepared = self::prepare_content( $post, $input );
if ( is_wp_error( $prepared ) ) {
return $prepared;
}
list( $input, $raw ) = $prepared;
if ( ( isset( $input['title'] ) && '' === trim( $input['title'] ) ) || ( isset( $input['content'] ) && '' === trim( wp_strip_all_tags( $input['content'] ) ) ) ) {
return new WP_Error( 'agent_publisher_empty', 'A published post cannot have an empty title or content.', array( 'status' => 400 ) );
}
$valid = self::validate_extras( $input );
if ( true === $valid ) {
$valid = self::validate_type_fields( $post->post_type, $input, $post->ID );
}
if ( is_wp_error( $valid ) ) {
return $valid;
}
$builder = self::refuse_builder_content( $post, $input );
if ( is_wp_error( $builder ) ) {
return $builder;
}
$allowed = Agent_Publisher_Policy::settings()['allowed_categories'];
if ( $allowed && isset( $input['categories'] ) && ( ! $input['categories'] || array_diff( array_map( 'intval', $input['categories'] ), $allowed ) ) ) {
return new WP_Error( 'agent_publisher_checks_failed', 'Agents may only use these category IDs on published posts: ' . implode( ', ', $allowed ) . '.', array( 'status' => 422 ) );
}
$uploaded = self::upload_featured( $input, $post->ID );
if ( is_wp_error( $uploaded ) ) {
return $uploaded;
}
// A live post's new featured image must pass the same image checks as a newly published one.
$new_image = $uploaded ? $uploaded : (int) ( $input['featured_media'] ?? 0 );
if ( $new_image ) {
$problems = Agent_Publisher_Policy::image_problems( $new_image );
if ( $problems ) {
if ( $uploaded ) {
wp_delete_attachment( $uploaded, true );
}
return new WP_Error( 'agent_publisher_checks_failed', 'Cannot use this featured image: ' . implode( '; ', $problems ) . '. The post was left unchanged.', array( 'status' => 422 ) );
}
}
$postarr = self::postarr( $input );
$postarr['ID'] = $post->ID;
if ( count( $postarr ) > 1 ) {
$id = self::update_post( $postarr, $raw );
if ( is_wp_error( $id ) ) {
if ( $uploaded ) {
wp_delete_attachment( $uploaded, true );
}
return $id;
}
}
self::save_extras( $post->ID, $input );
if ( $uploaded ) {
set_post_thumbnail( $post->ID, $uploaded );
Agent_Publisher_Policy::log( 'upload', $post->ID, wp_get_attachment_url( $uploaded ) );
}
if ( $uploaded || count( $postarr ) > 1 || array_intersect_key( $input, array_flip( array( 'categories', 'tags', 'featured_media', 'meta' ) ) ) ) {
Agent_Publisher_Policy::log( 'update_published', $post->ID );
}
return self::published_summary( get_post( $post->ID ) );
}
public static function upload_media( $input ) {
$post_id = (int) ( $input['post_id'] ?? 0 );
$id = self::sideload_image( $input, $post_id );
if ( is_wp_error( $id ) ) {
return $id;
}
if ( $post_id && ! empty( $input['set_featured'] ) ) {
set_post_thumbnail( $post_id, $id );
}
Agent_Publisher_Policy::log( 'upload', $post_id, wp_get_attachment_url( $id ) );
$file = wp_get_original_image_path( $id );
return self::image_info( $id ) + array(
'mime' => get_post_mime_type( $id ),
'bytes' => $file ? (int) filesize( $file ) : 0,
'sha256' => $file ? hash_file( 'sha256', $file ) : '',
'warnings' => Agent_Publisher_Policy::image_warnings( $id ),
);
}
public static function find_media( $input = array() ) {
$limit = max( 1, min( 50, (int) ( $input['limit'] ?? 20 ) ) );
$search = trim( (string) ( $input['search'] ?? '' ) );
$query = array(
'post_type' => 'attachment',
'post_status' => 'inherit',
'post_mime_type' => 'image',
'posts_per_page' => $limit,
'orderby' => 'date',
'order' => 'DESC',
'fields' => 'ids',
'no_found_rows' => true,
);
if ( ! empty( $input['mine'] ) ) {
$query['author'] = get_current_user_id();
}
if ( '' === $search ) {
$ids = get_posts( $query );
} else {
// Title/caption matches, plus file name matches (not covered by WordPress search).
$ids = array_unique( array_merge(
get_posts( $query + array( 's' => $search ) ),
get_posts( $query + array( 'meta_query' => array( array( 'key' => '_wp_attached_file', 'value' => $search, 'compare' => 'LIKE' ) ) ) ) // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_query -- bounded by posts_per_page.
) );
rsort( $ids );
$ids = array_slice( $ids, 0, $limit );
}
return array_map( function ( $id ) {
$att = get_post( $id );
$author = get_userdata( (int) $att->post_author );
$info = self::image_info( $id );
unset( $info['sizes'] );
return $info + array(
'title' => html_entity_decode( get_the_title( $id ) ),
'filename' => wp_basename( (string) get_attached_file( $id ) ),
'mime' => get_post_mime_type( $id ),
'date' => mysql2date( 'c', $att->post_date, false ),
'uploaded_by' => $author ? $author->display_name : '',
'attached_to' => (int) $att->post_parent,
'warnings' => Agent_Publisher_Policy::image_warnings( $id ),
);
}, array_map( 'intval', $ids ) );
}
public static function find_posts( $input = array() ) {
$types = self::post_types();
$type = $input['post_type'] ?? 'any';
$status = $input['status'] ?? 'any';
$limit = max( 1, min( 50, (int) ( $input['limit'] ?? 20 ) ) );
$query = array(
'post_type' => 'any' === $type ? $types : array( $type ),
'post_status' => 'any' === $status ? array( 'publish', 'draft', 'pending', 'future', 'private' ) : array( $status ),
'posts_per_page' => $limit * 3,
'orderby' => 'modified',
'order' => 'DESC',
'no_found_rows' => true,
'suppress_filters' => false,
);
if ( '' !== trim( (string) ( $input['search'] ?? '' ) ) ) {
$query['s'] = trim( (string) $input['search'] );
}
if ( ! empty( $input['mine'] ) ) {
$query['author'] = get_current_user_id();
}
$out = array();
foreach ( get_posts( $query ) as $p ) {
if ( true !== self::can_read( $p->ID ) ) {
continue;
}
$editable = in_array( $p->post_status, self::EDITABLE_STATUSES, true ) ? self::can_edit( $p->ID ) : self::can_manage( $p->ID );
$out[] = array(
'id' => (int) $p->ID,
'type' => $p->post_type,
'status' => $p->post_status,
'title' => html_entity_decode( get_the_title( $p ) ),
'author' => (string) get_the_author_meta( 'display_name', (int) $p->post_author ),
'modified' => mysql2date( 'c', $p->post_modified, false ),
'link' => (string) get_permalink( $p ),
'parent' => (int) $p->post_parent,
'can_edit' => true === $editable,
'page_builder' => self::builder_status( $p )['page_builder'],
);
if ( count( $out ) >= $limit ) {
break;
}
}
return $out;
}
/**
* Page builders that store a page's real layout outside post_content.
* slug => [ label, is the plugin active?, post meta key, value meaning "this page uses it" (null: any truthy value) ].
*/
private static function page_builders() {
return array(
'beaver-builder' => array( 'Beaver Builder', class_exists( 'FLBuilder' ) || defined( 'FL_BUILDER_VERSION' ), '_fl_builder_enabled', null ),
'elementor' => array( 'Elementor', defined( 'ELEMENTOR_VERSION' ), '_elementor_edit_mode', 'builder' ),
'divi' => array( 'Divi Builder', defined( 'ET_BUILDER_VERSION' ) || function_exists( 'et_pb_is_pagebuilder_used' ), '_et_pb_use_builder', 'on' ),
'wpbakery' => array( 'WPBakery', defined( 'WPB_VC_VERSION' ), '_wpb_vc_js_status', 'true' ),
);
}
/**
* Is this post's visible content its post_content, or does an active page
* builder draw it from its own data? Agents can't tell from the markup:
* converted pages keep builder class names (e.g. fl-row) so their CSS
* still applies.
*
* @return array page_builder (slug or null), content_is_live, note.
*/
public static function builder_status( $post ) {
$leftover = array();
foreach ( self::page_builders() as $slug => $builder ) {
list( $label, $active, $key, $value ) = $builder;
$meta = get_post_meta( $post->ID, $key, true );
$uses = null === $value ? ! empty( $meta ) : (string) $value === (string) $meta;
if ( ! $uses ) {
continue;
}
if ( $active ) {
return array(
'page_builder' => $slug,
'content_is_live' => false,
'note' => sprintf( 'This %1$s is managed by %2$s: its visible layout comes from %2$s\'s own data, not from content. Changes to content would not show and would be overwritten when someone saves it in %2$s. You can still change the title and other fields; ask the user to edit the layout in %2$s.', $post->post_type, $label ),
);
}
$leftover[] = $label;
}
return array(
'page_builder' => null,
'content_is_live' => true,
'note' => 'The content is exactly what visitors see: edit it directly.' . ( $leftover ? ' It contains class names and stored data from ' . implode( ', ', $leftover ) . ', which is no longer active on this site and is not used; ignore it.' : '' ),
);
}
/**
* Resolve `edits` into new content, or guard a full-content replacement.
*
* edits: each find must match exactly once; only the replacement text is
* filtered (for roles without unfiltered_html) and the rest of the stored
* content is kept byte for byte, so the save skips the content filter.
* content: for roles without unfiltered_html, refuse if WordPress's filter
* would remove markup the content already has (e.g. inline SVG), instead
* of silently breaking the page.
*
* @return array|WP_Error [ $input, $raw_save ].
*/
private static function prepare_content( $post, $input ) {
$unfiltered = current_user_can( 'unfiltered_html' );
if ( isset( $input['edits'] ) ) {
if ( isset( $input['content'] ) ) {
return new WP_Error( 'agent_publisher_bad_field', 'Pass content or edits, not both.', array( 'status' => 400 ) );
}
$content = (string) $post->post_content;
foreach ( array_values( (array) $input['edits'] ) as $i => $e ) {
$find = (string) ( $e['find'] ?? '' );
$n = '' === $find ? 0 : substr_count( $content, $find );
if ( 1 !== $n ) {
return new WP_Error( 'agent_publisher_edit_not_found', sprintf( 'Edit %1$d: "find" must match the current content exactly once; it matches %2$d times. Copy the exact text from get-post and include enough around it to be unique. Nothing was changed.', $i + 1, $n ), array( 'status' => 400 ) );
}
$replace = (string) ( $e['replace'] ?? '' );
$content = str_replace( $find, $unfiltered ? $replace : wp_kses_post( $replace ), $content );
}
$input['content'] = $content;
unset( $input['edits'] );
return array( $input, true );
}
if ( isset( $input['content'] ) && ! $unfiltered ) {
$lost = self::filtered_markup( (string) $post->post_content );
if ( $lost ) {
return new WP_Error( 'agent_publisher_markup_loss', sprintf( 'This %1$s contains markup the connected person\'s WordPress role can\'t save (%2$s). Replacing the whole content would remove it. Use edits to change specific text instead, or ask an Editor or Administrator. Nothing was changed.', $post->post_type, implode( ', ', $lost ) ), array( 'status' => 409 ) );
}
}
return array( $input, false );
}
/** What WordPress's post HTML filter would remove from $html, e.g. array( '13