Immutable. This exact content is served forever at /api/v1/blob/0cdc818da4cf7bf8.
---
name: find-artifacts
description: Use when discovering or loading run artifacts in npa agent without workflow/type/path allowlists.
---
# Find Artifacts (artifact-first)
Use this skill when the operator asks:
- "what can I view?"
- "show artifacts for this run"
- "load this recording/video/report"
- "browse outputs from storage"
## Model
Artifact-first means:
1. Enumerate what exists in storage.
2. Group by discovered run prefix.
3. Classify each object with a render hint.
4. Never hide unknown formats; degrade to download.
No workflow registry, path allowlist, or known-type gate is required.
## Agent API flow
All calls are same-origin (`/api/...`) on the authenticated agent VM.
1. Discover runs:
```http
GET /api/artifacts/runs?prefix=&limit=100
```
2. List artifacts for one run:
```http
GET /api/artifacts/run/{run_id}
```
3. Load one explicit artifact:
```http
POST /api/sim-viz/load-artifact
{
"run_id": "run-prefix",
"run_ref": "<server-issued opaque run reference>",
"project_id": "<selected project>",
"resource_bucket": "<selected bucket>",
"resolved_prefix": "<selected prefix, possibly empty>",
"source_selected": true,
"key": "path/to/run/object"
}
```
Preserve this exact source tuple from list response to card, thumbnail, preview,
download, and load action. `s3_uri` is provenance only: URI-only or otherwise
unscoped media requests are rejected with a stable 400 response because bucket
membership alone is not run-level authorization. Follow every artifact-page
cursor before computing preference; the shipped UI does this automatically.
4. Confirm loaded state:
```http
GET /api/sim-viz/status
```
Check `artifact_key`, `artifact_render`, `artifact_uri`, and `rerun_ready`.
## Render hints
- `rerun` (`.rrd`)
- `video` (`.mp4`, `.webm`, `.mov`)
- `image` (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`)
- `json`
- `text`
- `download` (fallback for unknown/new types)
Unknown types must stay visible/selectable.
## Safety
- Validate run ids (`validate_run_id`) before listing/loading.
- Reject traversal keys (`..`, empty segments).
- Surface S3 failures directly (`ok: false` or error detail); do not claim
success when load/list fails.
- Agent artifact discovery is S3-first and S3-only for run artifacts. The agent
must stage the configured artifact bucket credentials, upload completed run
artifacts there, and use `/api/artifacts/runs`, `/api/artifacts/run/{run_id}`,
and `/api/sim-viz/load-artifact` against that S3 data. Do not silently fall
back to `/opt/npa-agent/runs` for user-visible discovery.