[Feature] Add JobViewer SDK and unified job metadata (rock_meta.json)
- Dominant language
- Python
- Stars
- 485
- Forks
- 81
- Avg merge
- 16h 12m
- Merged PRs (30d)
- 8
Description
**Feature Category**
- [ ] Sandbox
- [ ] Actions
- [ ] Deployments
- [x] SDK & API
- [ ] Envhub
- [x] CLI
- [ ] Performance & Optimization
- [ ] Documentation & Examples
**Problem Statement**
After a job completes and its sandbox is destroyed, there is no way to query job artifacts, results, or status from the SDK. Harbor jobs persist structured data (result.json, trajectory, logs) to OSS via the mirror mechanism, but Bash jobs only upload a flat directory with no status metadata. Additionally, the two job types have completely different artifact structures, making unified status tracking impossible.
Key gaps:
1. No SDK client for reading job artifacts from OSS after sandbox teardown
2. Bash jobs have no completion marker — cannot distinguish "running" from "completed" or "crashed"
3. No unified metadata format across Harbor and Bash job types
**Proposed Solution**
1. **JobViewer SDK client** (`rock.sdk.job.viewer`): Synchronous Python API for reading job results, trials, trajectories, artifacts, and logs from OSS. Supports both direct AK/SK and admin STS authentication. Follows the same OSS key layout as Harbor viewer (`artifacts/{namespace}/{experiment_id}/{job_name}/...`).
2. **Unified job metadata** (`rock_meta.json`): Written inside the sandbox by wrapper scripts (crash-safe, independent of SDK process). Both BashTrial and HarborTrial inject prologue/epilogue blocks into their generated scripts:
- Prologue: writes `rock_meta.json` with `status: "running"` before main command
- Epilogue: updates to `status: "completed"/"failed"` with `exit_code` after main command
- Leverages existing upload mechanisms (ossutil for Bash, Harbor's OSS mirror for Harbor) — zero additional upload code
3. **CLI subcommands**: `rock job list/show/trials/trial` for querying job status and details from the terminal.
**Files Changed**
- `rock/sdk/job/viewer.py` — JobViewer client + data models
- `rock/sdk/job/meta.py` — JobMeta model + render_meta_json helper
- `rock/sdk/job/trial/bash.py` — inject meta writing into wrapper script
- `rock/sdk/job/trial/harbor.py` — inject meta writing into script template
- `rock/cli/command/job.py` — add viewer CLI subcommands
- `rock/sdk/job/__init__.py` — export JobViewer
- `CLAUDE.md` — update module descriptions
- 70 new unit tests (test_viewer.py + test_meta.py)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the listed files: rock/sdk/job/viewer.py, rock/sdk/job/meta.py, the Bash and Harbor trial scripts, and rock/cli/command/job.py. Read the existing Harbor viewer and run the referenced viewer and metadata unit tests to understand the OSS layout and models. Done means both job types write unified status metadata, the SDK reads the specified artifacts, and the four CLI subcommands and 70 tests are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend, cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 42/100