feat: Pipeline Settings M4 — generation history list + per-step I/O drill-down (v0.26.0)

CEO ask #5 complete: browsable paginated run list + full input/output inspection
per pipeline stage.

## What was built

### Generations list (prautoblogger-gen-history)
Hidden admin page (options.php-parent, priority 14) showing all pipeline runs newest
first, 20 per page. Each row: article title (linked to dossier when a post exists),
start date, status chip, distinct model(s), settled cost, duration. Queries bounded
(LIMIT/OFFSET) — no unbounded SELECT *.

New files:
- includes/admin/class-gen-history-query.php — paginated run list + per-run I/O queries
- includes/admin/class-gen-history-page.php  — hidden admin page + asset enqueue
- assets/css/gen-history.css, assets/js/gen-history.js — table + drill-down UI
- templates/admin/gen-history-page.php       — HTML template

### Per-step input + output drill-down (Stage I/O)
'Stage I/O' toggle opens an AJAX-loaded inline panel. For each generation_log stage:
  - input_system: system-role message content from generation_log.request_json
  - input_user: last user-role message from request_json (rendered instruction)
  - output: model response from run_stages.meta_json.output
  - output_pruned: true when meta_json present but output key absent (retention prune)

New AJAX endpoint: prautoblogger_gen_run_io (manage_options + nonce)
New file: includes/ajax/class-gen-run-io-handler.php

### gen-log INPUT/OUTPUT coverage verified
- INPUT: generation_log.request_json stores the chat body WITHOUT the Authorization
  header (Request_Recorder captures body after build_body(), before headers are added).
  System + user message content extracted and surfaced.
- OUTPUT: run_stages.meta_json.output is the LLM response text (Run_Stage_State::done()).
  Image/log-only stages (image_a, image_b, llm_research, image_prompt_rewrite) have no
  run_stages row; output is null, NOT pruned. Pruned outputs are flagged honestly.

### Dossier as entry point
Runs with a linked post show a 'Dossier' button deep-linking into the existing dossier
(which renders full per-stage I/O with editorial context). Stage I/O is complementary —
works for failed/orphan runs and provides the same data in a lighter inline UI.

### Stage-list-driven
Stage labels via Stage_Display_Map::label() — Phase 2b curate/seo appear automatically.

### Dead prautoblogger_pipeline_history endpoint
Not dead — it IS used by pipeline-settings.js for prompt version history (M3 feature).
Left in place. No dangling endpoint.

## M3 P2 sweep
- Removed dead data-preview-nonce and data-diff-nonce HTML attrs from
  pipeline-settings-prompt-panel.php (JS uses prabPipeline.*Nonce from
  wp_localize_script, not data-* attrs — confirmed by grep).
- Removed 3 redundant wp_create_nonce() calls from class-pipeline-settings-renderer.php
  (preview_nonce, history_nonce, diff_nonce keys that fed the now-removed dead attrs).
- Updated CONTEXT.md: added M3 + M4 terminology tables.
- Updated ARCHITECTURE.md: added ajax/ section to file tree; M3/M4 design notes.
- Updated INFORMATION-ARCHITECTURE.md: prautoblogger-gen-history entry.

## Security
- manage_options cap + prautoblogger_gen_run_io nonce on the AJAX endpoint.
- All output esc_html()/esc_url() server-side before JSON-encoding.
- JS renders prompt/response text via textContent — never innerHTML.
- No writes from history UI; request_json never contains auth headers.

## Version: v0.25.0 → v0.26.0

Agent-Session: pipeline-settings-m4
This commit is contained in:
PRAutoBlogger Engineer
2026-06-23 06:57:54 +00:00
parent 2569b08862
commit baae383c76
16 changed files with 1497 additions and 16 deletions

View File

@@ -0,0 +1,165 @@
<?php
declare(strict_types=1);
/**
* phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
*
* Registers and renders the Generation History admin page (M4).
*
* What: A browsable, paginated list of all previous generation runs —
* newest first, 20 per page. Each row shows the article title (when
* a post was produced), date, final run status, models used, total
* cost, and duration. "View dossier" links into the existing Article
* Dossier for full per-stage I/O detail (the dossier already renders
* input AND output for every stage). For failed/orphan runs (no post)
* a "Stage I/O" link opens the inline drill-down panel.
*
* Uses the canonical options.php-parent hidden-page pattern so the
* hookname is stable at registration time and request time (same
* design as the Dossier page — see CONVENTIONS.md §Hidden Admin Pages).
*
* Visible entry points:
* - PRAutoBlogger board "Generation History" link (nav added in M4).
* - PRAutoBlogger → Pipeline → History link (nav added in M4).
* - Direct URL: admin.php?page=prautoblogger-gen-history
*
* SECURITY: manage_options cap on render. AJAX drill-down uses a separate
* nonce (prautoblogger_gen_run_io) gated in Gen_Run_IO_Handler. The
* history list itself is read-only GET — no state changes. Output
* escaped in template via esc_html() / esc_url().
*
* Triggered by: PRAutoBlogger::register_admin_hooks() on `admin_menu` (priority 14).
* Dependencies: PRAutoBlogger_Gen_History_Query (list data),
* PRAutoBlogger_Dossier_Page (dossier URL builder).
*
* @see admin/class-gen-history-query.php -- List query + per-run I/O.
* @see ajax/class-gen-run-io-handler.php -- Per-run stage I/O AJAX.
* @see admin/class-dossier-page.php -- Dossier deep-link target.
* @see templates/admin/gen-history-page.php -- HTML template.
* @see ARCHITECTURE.md -- Admin pages table.
* @see CONVENTIONS.md -- §Hidden Admin Pages.
*/
class PRAutoBlogger_Gen_History_Page {
/** Admin page slug. */
public const PAGE_SLUG = 'prautoblogger-gen-history';
/**
* Canonical hidden-page parent (same pattern as Dossier_Page).
* Resolves hookname to `admin_page_{slug}` at both registration
* and request time — no $submenu manipulation required.
*/
public const PARENT_SLUG = 'options.php';
/** Nonce action for the gen-run I/O AJAX. */
public const IO_NONCE_ACTION = 'prautoblogger_gen_run_io';
/**
* Register the history page as a hidden admin page.
*
* @return void
*/
public function on_register_menu(): void {
add_submenu_page(
self::PARENT_SLUG,
__( 'Generation History', 'prautoblogger' ),
__( 'Generation History', 'prautoblogger' ),
'manage_options',
self::PAGE_SLUG,
array( $this, 'render_page' )
);
}
/**
* Render the generation history list page.
*
* @return void
*/
public function render_page(): void {
if ( ! current_user_can( 'manage_options' ) ) {
return;
}
// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only list page.
$page = isset( $_GET['paged'] ) ? max( 1, (int) $_GET['paged'] ) : 1;
$per_page = PRAutoBlogger_Gen_History_Query::PAGE_SIZE;
$query = new PRAutoBlogger_Gen_History_Query();
$result = $query->get_page( $page, $per_page );
$rows = $result['rows'];
$total = $result['total'];
$pages = max( 1, (int) ceil( $total / $per_page ) );
$pagination = array(
'current' => $page,
'total' => $pages,
'count' => $total,
'base' => admin_url( 'admin.php?page=' . self::PAGE_SLUG ),
);
include PRAUTOBLOGGER_PLUGIN_DIR . 'templates/admin/gen-history-page.php';
}
/**
* Enqueue assets for the generation history page.
*
* @param string $hook_suffix Current admin page hook suffix.
* @return void
*/
public function on_enqueue_assets( string $hook_suffix ): void {
if ( 'admin_page_' . self::PAGE_SLUG !== $hook_suffix ) {
return;
}
wp_enqueue_style(
'prautoblogger-admin',
PRAUTOBLOGGER_PLUGIN_URL . 'assets/css/admin.css',
array(),
PRAUTOBLOGGER_VERSION
);
wp_enqueue_style(
'prautoblogger-gen-history',
PRAUTOBLOGGER_PLUGIN_URL . 'assets/css/gen-history.css',
array( 'prautoblogger-admin' ),
PRAUTOBLOGGER_VERSION
);
wp_enqueue_script(
'prautoblogger-gen-history',
PRAUTOBLOGGER_PLUGIN_URL . 'assets/js/gen-history.js',
array(),
PRAUTOBLOGGER_VERSION,
true
);
wp_localize_script(
'prautoblogger-gen-history',
'prabGenHistory',
array(
'ajaxUrl' => admin_url( 'admin-ajax.php' ),
'action' => 'prautoblogger_gen_run_io',
'nonce' => wp_create_nonce( self::IO_NONCE_ACTION ),
'strings' => array(
'loading' => __( 'Loading…', 'prautoblogger' ),
'error' => __( 'Failed to load stage I/O — try again.', 'prautoblogger' ),
'noStages' => __( 'No generation log entries for this run.', 'prautoblogger' ),
'pruned' => __( '[Output pruned by retention policy]', 'prautoblogger' ),
'noOutput' => __( '[No output stored for this stage]', 'prautoblogger' ),
'noInput' => __( '[No request payload stored for this stage]', 'prautoblogger' ),
),
)
);
}
/**
* Build the URL to the generation history page.
*
* @param int $page Optional page number.
* @return string Admin URL.
*/
public static function url( int $page = 1 ): string {
$base = admin_url( 'admin.php?page=' . self::PAGE_SLUG );
return $page > 1 ? $base . '&paged=' . $page : $base;
}
}

View File

@@ -0,0 +1,288 @@
<?php
declare(strict_types=1);
/**
* phpcs:ignore WordPress.Files.FileName.InvalidClassFileName -- class naming convention differs from WordPress standard
*
* Paginated query over the runs ledger for the Generation History page (M4).
*
* What: Returns a bounded, paginated list of previous generation runs,
* newest first. Each row includes the linked article title (when
* the run produced a published/draft post), final status, total
* settled cost, duration, and the distinct model(s) used (from
* generation_log). Query is bounded (LIMIT/OFFSET) — never does an
* unbounded SELECT *.
*
* Also exposes a per-run stage I/O method used by the AJAX drill-
* down: returns every generation_log row for a run (input from
* request_json) plus the corresponding run_stages output
* (meta_json). This is intentionally separate from the dossier's
* Dossier_Data_Assembler so it works without a post_id (orphan/
* failed runs have no post).
*
* SECURITY: request_json is stored without API keys (the provider's
* build_body() never includes the Authorization header; only the JSON
* body is captured by Request_Recorder). All output is plain data;
* escaping is the caller's responsibility (Gen_Run_IO_Handler and the
* template call esc_html).
*
* Triggered by: PRAutoBlogger_Gen_History_Page (list) and
* PRAutoBlogger_Gen_Run_IO_Handler (drill-down).
* Dependencies: WordPress $wpdb.
*
* @see admin/class-gen-history-page.php -- List page (entry point).
* @see ajax/class-gen-run-io-handler.php -- Per-run I/O drill-down AJAX.
* @see admin/class-dossier-gen-log-query.php -- Dossier counterpart (post-scoped).
* @see ARCHITECTURE.md -- Database schema (runs, generation_log).
*/
class PRAutoBlogger_Gen_History_Query {
/** Default page size (max runs per page). */
public const PAGE_SIZE = 20;
/** Maximum page size to prevent abuse. */
public const PAGE_SIZE_MAX = 100;
/**
* Fetch a paginated list of generation runs, newest first.
*
* Each row in the result carries:
* run_id, status, ceiling_usd, settled_usd, started_at, finished_at,
* post_id (nullable — from postmeta), post_title (nullable),
* cost_total (SUM from gen_log), models (comma-separated distinct),
* duration_seconds (UNIX diff finished_at - started_at, or null).
*
* @param int $page 1-based page number.
* @param int $per_page Rows per page (capped at PAGE_SIZE_MAX).
* @return array{rows: list<array<string,mixed>>, total: int}
*/
public function get_page( int $page = 1, int $per_page = self::PAGE_SIZE ): array {
global $wpdb;
if ( null === $wpdb ) {
return array( 'rows' => array(), 'total' => 0 );
}
$per_page = min( max( 1, $per_page ), self::PAGE_SIZE_MAX );
$offset = ( max( 1, $page ) - 1 ) * $per_page;
$runs_table = $wpdb->prefix . 'prautoblogger_runs';
$log_table = $wpdb->prefix . 'prautoblogger_generation_log';
$meta_table = $wpdb->postmeta;
// Total count for pagination.
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
$total = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$runs_table}" );
// Join runs → postmeta (run_id stored in _prautoblogger_run_id) for title.
// LEFT JOIN gen_log to aggregate cost + models. Bounded by LIMIT.
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
$rows = $wpdb->get_results(
$wpdb->prepare(
"SELECT
r.run_id,
r.status,
r.ceiling_usd,
r.settled_usd,
r.started_at,
r.finished_at,
pm.post_id,
p.post_title,
p.post_status as post_status,
COALESCE(SUM(CASE WHEN gl.response_status = 'success' THEN gl.estimated_cost ELSE 0 END), 0) AS cost_total,
GROUP_CONCAT(DISTINCT gl.model ORDER BY gl.model SEPARATOR ', ') AS models,
CASE WHEN r.finished_at IS NOT NULL
THEN TIMESTAMPDIFF(SECOND, r.started_at, r.finished_at)
ELSE NULL
END AS duration_seconds
FROM {$runs_table} r
LEFT JOIN {$meta_table} pm
ON pm.meta_key = '_prautoblogger_run_id'
AND pm.meta_value = r.run_id
LEFT JOIN {$wpdb->posts} p
ON p.ID = pm.post_id
LEFT JOIN {$log_table} gl
ON gl.run_id = r.run_id
GROUP BY r.run_id, r.status, r.ceiling_usd, r.settled_usd,
r.started_at, r.finished_at, pm.post_id, p.post_title, p.post_status
ORDER BY r.started_at DESC
LIMIT %d OFFSET %d",
$per_page,
$offset
),
ARRAY_A
);
return array(
'rows' => is_array( $rows ) ? $rows : array(),
'total' => $total,
);
}
/**
* Fetch per-stage input + output for one run.
*
* INPUT: extracted from generation_log.request_json (the assembled
* messages the LLM received). Auth headers are never stored — only
* the body. Returns the user-role message content (the rendered
* instruction) and the system message when present.
*
* OUTPUT: extracted from run_stages.meta_json.output (the LLM's
* response text). When meta_json is NULL (pruned per retention
* policy) or has no output key, output is null — reported honestly.
*
* Stages are ordered by generation_log.id ASC (insertion order),
* then enriched with the matching run_stages snapshot where found.
*
* @param string $run_id Pipeline run UUID.
* @return list<array<string, mixed>> Stage rows, each with keys:
* stage, model, agent_role, prompt_tokens, completion_tokens,
* estimated_cost, response_status, error_message, created_at,
* input_system (string|null), input_user (string|null),
* output (string|null), output_pruned (bool).
*/
public function get_run_io( string $run_id ): array {
global $wpdb;
if ( null === $wpdb || '' === $run_id ) {
return array();
}
$log_table = $wpdb->prefix . 'prautoblogger_generation_log';
$stages_table = $wpdb->prefix . 'prautoblogger_run_stages';
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
$log_rows = $wpdb->get_results(
$wpdb->prepare(
"SELECT id, stage, model, agent_role,
prompt_tokens, completion_tokens, estimated_cost,
request_json, response_status, error_message, created_at
FROM {$log_table}
WHERE run_id = %s
ORDER BY id ASC",
$run_id
),
ARRAY_A
);
if ( ! is_array( $log_rows ) ) {
return array();
}
// Load run_stages output snapshot (keyed by stage+agent_role).
$stage_outputs = array();
if ( PRAutoBlogger_Run_Stage_State::is_available() ) {
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
$stage_rows = $wpdb->get_results(
$wpdb->prepare(
"SELECT stage, agent_role, meta_json
FROM {$stages_table}
WHERE run_id = %s",
$run_id
),
ARRAY_A
);
foreach ( ( $stage_rows ?? array() ) as $sr ) {
$key = (string) $sr['stage'] . ':' . (string) ( $sr['agent_role'] ?? '' );
$stage_outputs[ $key ] = $sr['meta_json'];
}
}
$result = array();
foreach ( $log_rows as $row ) {
$stage = (string) ( $row['stage'] ?? '' );
$agent_role = (string) ( $row['agent_role'] ?? '' );
$stage_key = $stage . ':' . $agent_role;
// Extract INPUT from request_json messages array.
$input_system = null;
$input_user = null;
if ( ! empty( $row['request_json'] ) ) {
$body = json_decode( (string) $row['request_json'], true );
if ( is_array( $body ) && ! empty( $body['messages'] ) ) {
foreach ( (array) $body['messages'] as $msg ) {
if ( ! is_array( $msg ) ) {
continue;
}
$role = (string) ( $msg['role'] ?? '' );
$content = is_string( $msg['content'] ?? null ) ? $msg['content'] : '';
if ( 'system' === $role && '' !== $content ) {
$input_system = $content;
} elseif ( 'user' === $role && '' !== $content ) {
$input_user = $content;
}
}
}
}
// Extract OUTPUT from run_stages meta_json.
$output = null;
$output_pruned = false;
$meta_raw = $stage_outputs[ $stage_key ] ?? null;
if ( null === $meta_raw ) {
// Stage may not exist in run_stages (log-only stage e.g. image_a).
$output_pruned = false;
} else {
$meta = json_decode( (string) $meta_raw, true );
if ( is_array( $meta ) && isset( $meta['output'] ) ) {
$output = (string) $meta['output'];
} else {
// meta_json present but no 'output' key = pruned by retention.
$output_pruned = true;
}
}
$result[] = array(
'stage' => $stage,
'model' => (string) ( $row['model'] ?? '' ),
'agent_role' => $agent_role,
'prompt_tokens' => (int) ( $row['prompt_tokens'] ?? 0 ),
'completion_tokens' => (int) ( $row['completion_tokens'] ?? 0 ),
'estimated_cost' => (float) ( $row['estimated_cost'] ?? 0 ),
'response_status' => (string) ( $row['response_status'] ?? '' ),
'error_message' => (string) ( $row['error_message'] ?? '' ),
'created_at' => (string) ( $row['created_at'] ?? '' ),
'input_system' => $input_system,
'input_user' => $input_user,
'output' => $output,
'output_pruned' => $output_pruned,
);
}
return $result;
}
/**
* Fetch minimal run metadata (status, started_at, post_id/title) for
* the drill-down header. Used by Gen_Run_IO_Handler.
*
* @param string $run_id Pipeline run UUID.
* @return array<string, mixed>|null
*/
public function get_run_meta( string $run_id ): ?array {
global $wpdb;
if ( null === $wpdb || '' === $run_id ) {
return null;
}
$runs_table = $wpdb->prefix . 'prautoblogger_runs';
$meta_table = $wpdb->postmeta;
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching
$row = $wpdb->get_row(
$wpdb->prepare(
"SELECT r.run_id, r.status, r.settled_usd, r.started_at, r.finished_at,
pm.post_id, p.post_title
FROM {$runs_table} r
LEFT JOIN {$meta_table} pm
ON pm.meta_key = '_prautoblogger_run_id'
AND pm.meta_value = r.run_id
LEFT JOIN {$wpdb->posts} p
ON p.ID = pm.post_id
WHERE r.run_id = %s
LIMIT 1",
$run_id
),
ARRAY_A
);
return is_array( $row ) ? $row : null;
}
}

View File

@@ -66,10 +66,8 @@ class PRAutoBlogger_Pipeline_Settings_Renderer {
'global_fields' => $this->build_option_field_values( 'global' ),
'step_context' => $step_context,
'step_fields' => $step_context ? $this->build_option_field_values( $step_context ) : array(),
// M3: AJAX nonces localized into the view for JS use.
'preview_nonce' => wp_create_nonce( PRAutoBlogger_Pipeline_Preview_Handler::ACTION ),
'history_nonce' => wp_create_nonce( PRAutoBlogger_Pipeline_History_Handler::ACTION_HISTORY ),
'diff_nonce' => wp_create_nonce( PRAutoBlogger_Pipeline_History_Handler::ACTION_DIFF ),
// M3: AJAX action names passed to the template for data-* attrs.
// Nonces are localised via wp_localize_script in Pipeline_Settings_Page::on_enqueue_assets().
'preview_action' => PRAutoBlogger_Pipeline_Preview_Handler::ACTION,
'history_action' => PRAutoBlogger_Pipeline_History_Handler::ACTION_HISTORY,
'diff_action' => PRAutoBlogger_Pipeline_History_Handler::ACTION_DIFF,