fix(runs): bound artifact inventory (#11089)

AI assistance: OpenAI gpt-5.6-sol via OpenCode implemented the bounded, filtered artifact inventory and tests; Chris Huber reviewed and owns this change.

Author: Chris Huber

crates/homeboy-cli/src/commands/runs/artifact_index_tests.rs

@@ -2,6 +2,7 @@ use homeboy::core::observation::{NewRunRecord, ObservationStore, RunStatus};
 use homeboy::test_support::with_isolated_home;
 use serde_json::Value;
 
+use super::types::RunsArtifactsArgs;
 use super::{handlers, list_runs, RunsListArgs, RunsOutput};
 
 struct XdgGuard(Option<String>);
@@ -223,6 +224,90 @@ fn runs_artifacts_surfaces_matrix_summary_from_typed_packets() {
     });
 }
 
+#[test]
+fn runs_artifacts_pages_large_inventory_and_filters_before_rendering() {
+    with_isolated_home(|home| {
+        let _xdg = XdgGuard::unset();
+        let store = ObservationStore::open_initialized().expect("store");
+        let run = store
+            .start_run(sample_run(
+                "bench",
+                "homeboy",
+                "inventory-rig",
+                serde_json::json!({}),
+            ))
+            .expect("run");
+        let artifact_path = home.path().join("visual.png");
+        std::fs::write(&artifact_path, b"png").expect("artifact bytes");
+        for index in 0..240 {
+            store
+                .record_artifact_with_metadata(
+                    &run.id,
+                    if index % 3 == 0 { "visual_diff" } else { "log" },
+                    &artifact_path,
+                    serde_json::json!({
+                        "fixture_id": if index % 3 == 0 { "fixture-89" } else { "other" },
+                        "surface_id": if index % 3 == 0 { "desktop" } else { "other" },
+                        "scenario_id": "visual-regression",
+                    }),
+                )
+                .expect("record artifact");
+        }
+
+        let (output, _) = handlers::artifacts_from_args(RunsArtifactsArgs {
+            run_id: run.id.clone(),
+            runner: None,
+            pull: false,
+            pull_dir: None,
+            token: None,
+            kind: None,
+            mime: None,
+            original_path: None,
+            path_suffix: None,
+            fixture: None,
+            surface: None,
+            scenario: None,
+            name_glob: None,
+            limit: 50,
+            offset: 0,
+            full: false,
+        })
+        .expect("bounded listing");
+        let RunsOutput::Artifacts(output) = output else {
+            panic!("artifacts output")
+        };
+        assert_eq!(output.artifacts.len(), 50);
+        let page = output.page.expect("page metadata");
+        assert_eq!(page.total, 240);
+        assert_eq!(page.next_offset, Some(50));
+
+        let (output, _) = handlers::artifacts_from_args(RunsArtifactsArgs {
+            run_id: run.id,
+            runner: None,
+            pull: false,
+            pull_dir: None,
+            token: None,
+            kind: Some("visual_diff".to_string()),
+            mime: Some("image/png".to_string()),
+            original_path: None,
+            path_suffix: Some("visual.png".to_string()),
+            fixture: Some("fixture-89".to_string()),
+            surface: Some("desktop".to_string()),
+            scenario: Some("visual-regression".to_string()),
+            name_glob: Some("visual_*".to_string()),
+            limit: 100,
+            offset: 0,
+            full: false,
+        })
+        .expect("filtered listing");
+        let RunsOutput::Artifacts(output) = output else {
+            panic!("artifacts output")
+        };
+        assert_eq!(output.artifacts.len(), 80);
+        assert_eq!(output.page.expect("page metadata").total, 80);
+    });
+}
+
 #[test]
 fn runs_artifacts_classifies_persisted_bench_artifact_from_metadata() {
     with_isolated_home(|home| {

crates/homeboy-cli/src/commands/runs/handlers.rs

@@ -14,7 +14,8 @@ use homeboy::core::artifact_address::ArtifactAddress;
 use homeboy::core::observation::evidence_report::directory_publication_guidance;
 use homeboy::core::observation::runs_service;
 use homeboy::core::observation::{
-    merge_metadata, FindingListFilter, ObservationStore, RunListFilter, RunRecord, RunStatus,
+    merge_metadata, ArtifactListFilter, FindingListFilter, ObservationStore, RunListFilter,
+    RunRecord, RunStatus,
 };
 use homeboy::core::resource_lifecycle_index::resource_lifecycle_index_from_artifacts;
 use homeboy::core::validation_progress::ValidationProgressLedger;
@@ -27,11 +28,12 @@ use super::common::{run_summaries_with_artifact_indexes, RunSummary};
 use super::types::{
     actionable_for_run_detail, actionable_for_run_list, RunDetail, RunsArtifactArgs,
     RunsArtifactCommand, RunsArtifactCommandHint, RunsArtifactGetArgs, RunsArtifactGetOutput,
-    RunsArtifactPathGuide, RunsArtifactPullEntry, RunsArtifactPullSummary, RunsArtifactsArgs,
-    RunsArtifactsOutput, RunsCancelOutput, RunsDirectoryArtifactPublicationGuidance,
-    RunsEnvKeyOutput, RunsEnvOutput, RunsEnvSourceLayerOutput, RunsEnvSummary,
-    RunsFieldSelectionOutput, RunsListArgs, RunsListOutput, RunsOutput, RunsResumePlanOutput,
-    RunsSelectedField, RunsShowOutput, RunsStaleRunSummary,
+    RunsArtifactPage, RunsArtifactPathGuide, RunsArtifactPullEntry, RunsArtifactPullSummary,
+    RunsArtifactsArgs, RunsArtifactsOutput, RunsCancelOutput,
+    RunsDirectoryArtifactPublicationGuidance, RunsEnvKeyOutput, RunsEnvOutput,
+    RunsEnvSourceLayerOutput, RunsEnvSummary, RunsFieldSelectionOutput, RunsListArgs,
+    RunsListOutput, RunsOutput, RunsResumePlanOutput, RunsSelectedField, RunsShowOutput,
+    RunsStaleRunSummary,
 };
 use super::{reconcile, remote, remote_artifact, CmdResult};
 
@@ -567,6 +569,20 @@ pub fn artifacts(run_id: &str) -> CmdResult<RunsOutput> {
         runner: None,
         pull: false,
         pull_dir: None,
+        token: None,
+        kind: None,
+        mime: None,
+        original_path: None,
+        path_suffix: None,
+        fixture: None,
+        surface: None,
+        scenario: None,
+        name_glob: None,
+        limit: 50,
+        offset: 0,
+        // Preserve the direct test helper's historical exhaustive projection;
+        // the public CLI defaults to the bounded discovery page.
+        full: true,
     })
 }
 
@@ -582,13 +598,61 @@ pub fn artifacts_from_args(args: RunsArtifactsArgs) -> CmdResult<RunsOutput> {
                 ]),
             ));
         }
-        return remote::runner_artifacts(runner_id, &args.run_id);
+        return remote::runner_artifacts(runner_id, &args);
     }
 
     let store = ObservationStore::open_initialized()?;
     let run = runs_service::require_run(&store, &args.run_id)?;
     let run_id = run.id;
-    let artifacts = runs_service::list_artifacts_for_run(&store, &run_id)?;
+    let filter = ArtifactListFilter {
+        token: args.token.clone(),
+        kind: args.kind.clone(),
+        mime: args.mime.clone(),
+        original_path: args.original_path.clone(),
+        path_suffix: args.path_suffix.clone(),
+        fixture: args.fixture.clone(),
+        surface: args.surface.clone(),
+        scenario: args.scenario.clone(),
+        name_glob: args.name_glob.clone(),
+        limit: args.limit,
+        offset: args.offset,
+    };
+    let page = if args.full {
+        None
+    } else {
+        Some(store.list_artifacts_page(&run_id, &filter)?)
+    };
+    let artifacts = match page.as_ref() {
+        Some(page) => page.artifacts.clone(),
+        None => runs_service::list_artifacts_for_run(&store, &run_id)?,
+    };
+    if !args.full {
+        let page = page.expect("bounded artifact page is present");
+        return Ok((
+            RunsOutput::Artifacts(RunsArtifactsOutput {
+                command: "runs.artifacts",
+                run_id: run_id.clone(),
+                runner_id: None,
+                path_guide: RunsArtifactPathGuide::for_listing(&run_id, None),
+                next_commands: artifact_get_command_hints(&run_id, &artifacts),
+                artifacts,
+                page: Some(RunsArtifactPage {
+                    total: page.total,
+                    limit: page.limit,
+                    offset: page.offset,
+                    next_offset: (page.offset + page.artifacts.len() < page.total)
+                        .then_some(page.offset + page.artifacts.len()),
+                }),
+                resource_lifecycle_index: None,
+                directory_publication: Vec::new(),
+                preview_entrypoints: Vec::new(),
+                matrix_summary: None,
+                fuzz_result_envelopes: Vec::new(),
+                pull: None,
+            }),
+            0,
+        ));
+    }
     let preview_entrypoints = artifacts
         .iter()
         .flat_map(homeboy::core::artifacts::html_preview_entrypoints)
@@ -624,6 +688,7 @@ pub fn artifacts_from_args(args: RunsArtifactsArgs) -> CmdResult<RunsOutput> {
             path_guide: RunsArtifactPathGuide::for_listing(&run_id, None),
             next_commands: artifact_get_command_hints(&run_id, &artifacts),
             artifacts,
+            page: None,
             resource_lifecycle_index,
             directory_publication,
             preview_entrypoints,
@@ -1389,6 +1454,18 @@ mod pull_tests {
             runner: Some("lab".to_string()),
             pull: true,
             pull_dir: None,
+            token: None,
+            kind: None,
+            mime: None,
+            original_path: None,
+            path_suffix: None,
+            fixture: None,
+            surface: None,
+            scenario: None,
+            name_glob: None,
+            limit: 50,
+            offset: 0,
+            full: false,
         });
         let Err(err) = result else {
             panic!("--pull with --runner should fail");

crates/homeboy-cli/src/commands/runs/remote.rs

@@ -8,8 +8,8 @@ use homeboy::core::Error;
 use homeboy::runner::runners as runner;
 
 use super::types::{
-    actionable_for_run_list, RunsArtifactGetArgs, RunsArtifactPathGuide, RunsArtifactsOutput,
-    RunsDirectoryArtifactPublicationGuidance,
+    actionable_for_run_list, RunsArtifactGetArgs, RunsArtifactPage, RunsArtifactPathGuide,
+    RunsArtifactsArgs, RunsArtifactsOutput, RunsDirectoryArtifactPublicationGuidance,
 };
 use super::{remote_artifact, CmdResult, RunSummary, RunsListArgs, RunsListOutput, RunsOutput};
 
@@ -229,12 +229,49 @@ fn active_runner_job_run_summary_if_durable(
     })
 }
 
-pub fn runner_artifacts(runner_id: &str, run_id: &str) -> CmdResult<RunsOutput> {
+pub fn runner_artifacts(runner_id: &str, args: &RunsArtifactsArgs) -> CmdResult<RunsOutput> {
+    let run_id = &args.run_id;
+    let mut query = Vec::new();
+    for (key, value) in [
+        ("token", args.token.as_deref()),
+        ("kind", args.kind.as_deref()),
+        ("mime", args.mime.as_deref()),
+        ("original_path", args.original_path.as_deref()),
+        ("path_suffix", args.path_suffix.as_deref()),
+        ("fixture", args.fixture.as_deref()),
+        ("surface", args.surface.as_deref()),
+        ("scenario", args.scenario.as_deref()),
+        ("name_glob", args.name_glob.as_deref()),
+    ] {
+        if let Some(value) = value {
+            query.push(format!("{key}={}", encode_uri_component(value)));
+        }
+    }
+    if !args.full {
+        query.push(format!("limit={}", args.limit.clamp(1, 1000)));
+        query.push(format!("offset={}", args.offset.max(0)));
+    } else {
+        query.push("full=1".to_string());
+    }
+    let query = (!query.is_empty())
+        .then(|| format!("?{}", query.join("&")))
+        .unwrap_or_default();
     let data = runner::daemon_api_get(
         runner_id,
-        &format!("/runs/{}/artifacts", encode_uri_component(run_id)),
+        &format!("/runs/{}/artifacts{}", encode_uri_component(run_id), query),
     )?;
     let artifacts = parse_runner_artifacts(&data)?;
+    let page = data.get("page").and_then(|page| {
+        Some(RunsArtifactPage {
+            total: page.get("total")?.as_u64()? as usize,
+            limit: page.get("limit")?.as_u64()? as usize,
+            offset: page.get("offset")?.as_u64()? as usize,
+            next_offset: page
+                .get("next_offset")
+                .and_then(serde_json::Value::as_u64)
+                .map(|value| value as usize),
+        })
+    });
     let directory_publication = directory_publication_guidance_for_artifacts(&artifacts);
     let resource_lifecycle_index = resource_lifecycle_index_from_artifacts(&artifacts)?;
 
@@ -245,6 +282,7 @@ pub fn runner_artifacts(runner_id: &str, run_id: &str) -> CmdResult<RunsOutput>
             runner_id: Some(runner_id.to_string()),
             path_guide: RunsArtifactPathGuide::for_listing(run_id, Some(runner_id)),
             artifacts,
+            page,
             next_commands: Vec::new(),
             resource_lifecycle_index,
             directory_publication,

crates/homeboy-cli/src/commands/runs/types.rs

@@ -383,6 +383,10 @@ pub struct RunsArtifactsOutput {
     pub runner_id: Option<String>,
     pub path_guide: RunsArtifactPathGuide,
     pub artifacts: Vec<ArtifactRecord>,
+    /// Persisted inventory page details. `--full` omits the limit so legacy
+    /// callers retain the exhaustive listing contract.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub page: Option<RunsArtifactPage>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub resource_lifecycle_index: Option<ResourceLifecycleIndex>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
@@ -401,6 +405,14 @@ pub struct RunsArtifactsOutput {
     pub pull: Option<RunsArtifactPullSummary>,
 }
 
+#[derive(Serialize)]
+pub struct RunsArtifactPage {
+    pub total: usize,
+    pub limit: usize,
+    pub offset: usize,
+    pub next_offset: Option<usize>,
+}
+
 #[derive(Serialize)]
 pub struct RunsArtifactCommandHint {
     pub artifact_id: String,
@@ -504,6 +516,42 @@ pub struct RunsArtifactsArgs {
     /// run-scoped path under the operator-local artifact root.
     #[arg(long, requires = "pull")]
     pub pull_dir: Option<PathBuf>,
+    /// Exact persisted artifact id token.
+    #[arg(long)]
+    pub token: Option<String>,
+    /// Exact artifact kind.
+    #[arg(long)]
+    pub kind: Option<String>,
+    /// Exact MIME type.
+    #[arg(long)]
+    pub mime: Option<String>,
+    /// Exact original persisted path.
+    #[arg(long)]
+    pub original_path: Option<String>,
+    /// Match a persisted path suffix.
+    #[arg(long)]
+    pub path_suffix: Option<String>,
+    /// Exact `fixture_id` artifact metadata value.
+    #[arg(long)]
+    pub fixture: Option<String>,
+    /// Exact `surface_id` artifact metadata value.
+    #[arg(long)]
+    pub surface: Option<String>,
+    /// Exact `scenario_id` artifact metadata value.
+    #[arg(long)]
+    pub scenario: Option<String>,
+    /// Glob match against the artifact kind/name.
+    #[arg(long)]
+    pub name_glob: Option<String>,
+    /// Maximum records in this page (1-1000).
+    #[arg(long, default_value_t = 50)]
+    pub limit: i64,
+    /// Number of matching records to skip before this page.
+    #[arg(long, default_value_t = 0)]
+    pub offset: i64,
+    /// Retain the exhaustive legacy listing and derived summaries.
+    #[arg(long)]
+    pub full: bool,
 }
 
 #[derive(Serialize)]