Skip to content

Official Codebase of 3DCodeVerse

Python

harness: refactor batch 1 — shared foundations (TrackInfo/ENTRY_FILE registries, Settings.backends(), GateFinding.as_line, typed AgentJob, RunOptions, codeverse/proc.py; +28 tests, 915 green)

gaoypenga0491faea8a5
diff --git a/harness/bench/out/articulated_v1_flash/battery.json b/harness/bench/out/articulated_v1_flash/battery.json
new file mode 100644
index 00000000..5d4910f3
--- /dev/null
+++ b/harness/bench/out/articulated_v1_flash/battery.json
@@ -0,0 +1,198 @@
+{
+ "battery": {
+ "name": "articulated_v1",
+ "track": "articulated_object",
+ "language": "urdf_blender",
+ "description": "12 articulated-object prompts (URDF + bpy link meshes), 4 per tier. must_have items name the joints the judge/FK sweep must verify.\n",
+ "prompts": [
+ {
+ "id": "art_easy_cabinet_door",
+ "prompt": "a kitchen wall cabinet with a single hinged door that swings open 110 degrees",
+ "tier": "easy",
+ "category": "furniture",
+ "must_have": [
+ "cabinet box",
+ "one door on a vertical hinge axis",
+ "door swings outward up to 110 degrees",
+ "handle on the free edge"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_easy_drawer_unit",
+ "prompt": "a bedside drawer unit with two drawers that slide out",
+ "tier": "easy",
+ "category": "furniture",
+ "must_have": [
+ "carcass",
+ "two drawers on prismatic slides",
+ "drawers pull out at least 30 cm",
+ "drawer pulls"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_easy_laptop",
+ "prompt": "a laptop whose screen lid opens from closed to 135 degrees on a hinge at the back edge",
+ "tier": "easy",
+ "category": "electronics",
+ "must_have": [
+ "base with keyboard",
+ "lid with screen",
+ "revolute hinge along the back edge",
+ "range 0 to 135 degrees"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_easy_scissors",
+ "prompt": "a pair of scissors with two blades pivoting about a central screw",
+ "tier": "easy",
+ "category": "tools",
+ "must_have": [
+ "two blade-and-handle halves",
+ "one revolute pivot at the screw",
+ "blades cross when closed",
+ "opens about 60 degrees"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_med_folding_chair",
+ "prompt": "a folding chair whose seat lifts up and whose front legs pivot toward the back legs to fold flat",
+ "tier": "medium",
+ "category": "furniture",
+ "must_have": [
+ "seat hinged to the frame",
+ "front leg frame pivoting about a cross bar",
+ "back rest",
+ "folds to a flat state"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_med_desk_lamp",
+ "prompt": "a desk lamp with a round base, a lower arm that pivots at the base and an upper arm that pivots at the elbow, ending in a shade",
+ "tier": "medium",
+ "category": "lighting",
+ "must_have": [
+ "weighted base",
+ "lower arm revolute at base",
+ "upper arm revolute at elbow",
+ "shade at the tip",
+ "both joints have limits"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_med_toolbox",
+ "prompt": "a metal toolbox with a lid hinged along the back edge and a fold-down carry handle on top of the lid",
+ "tier": "medium",
+ "category": "tools",
+ "must_have": [
+ "box body",
+ "lid hinged at the rear edge",
+ "handle hinged on the lid",
+ "lid opens 100 degrees",
+ "latch on the front"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_med_wheelbarrow",
+ "prompt": "a wheelbarrow with a spinning front wheel and a tray that tips forward on its axle to dump",
+ "tier": "medium",
+ "category": "garden",
+ "must_have": [
+ "tray",
+ "two handles",
+ "two rear legs",
+ "front wheel on a continuous axle joint",
+ "tipping joint for the tray"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_hard_door_handle",
+ "prompt": "a house door in its frame with hinges, a lever handle that rotates down 40 degrees, and a latch bolt that retracts when the handle turns",
+ "tier": "hard",
+ "category": "architecture",
+ "must_have": [
+ "door frame",
+ "door on vertical hinges",
+ "lever handle revolute",
+ "latch bolt prismatic",
+ "door swings 90 degrees"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_hard_treasure_chest",
+ "prompt": "a wooden treasure chest with a domed lid on rear hinges, a hasp that flips over a staple, and a small inner tray that slides sideways",
+ "tier": "hard",
+ "category": "props",
+ "must_have": [
+ "chest body",
+ "domed lid revolute at rear",
+ "hasp revolute on the lid",
+ "sliding inner tray",
+ "iron bands"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_hard_swivel_chair",
+ "prompt": "an office swivel chair with a five-star base on casters, a gas lift that raises the seat, a seat that swivels, and a backrest that tilts back",
+ "tier": "hard",
+ "category": "furniture",
+ "must_have": [
+ "five-arm base with five caster wheels",
+ "prismatic gas lift",
+ "continuous swivel joint",
+ "backrest tilt joint with limits",
+ "armrests"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "art_hard_bicycle_wheel_stand",
+ "prompt": "a bicycle front wheel and fork on a repair stand, with the wheel spinning on its axle, the fork turning about the steering tube, and a brake caliper whose arms pinch the rim",
+ "tier": "hard",
+ "category": "vehicles",
+ "must_have": [
+ "spoked wheel on a continuous axle joint",
+ "fork on a steering revolute joint",
+ "two brake arms pivoting toward the rim",
+ "stand base"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ }
+ ]
+ },
+ "options": {
+ "generator": "api-agent:gemini:gemini-3.7-flash",
+ "planner": null,
+ "judge": "gemini:gemini-3.1-pro-preview",
+ "rounds": 3,
+ "max_usd": 2.0,
+ "max_minutes": 60.0,
+ "parallel": 3,
+ "limit": null,
+ "ids": [],
+ "tiers": [],
+ "resume": true
+ },
+ "started_at": "2026-08-23T11:10:55.448078+00:00"
+}
\ No newline at end of file
diff --git a/harness/bench/out/articulated_v1_flash/results.jsonl b/harness/bench/out/articulated_v1_flash/results.jsonl
new file mode 100644
index 00000000..973360f9
--- /dev/null
+++ b/harness/bench/out/articulated_v1_flash/results.jsonl
@@ -0,0 +1,2 @@
+{"id":"art_easy_cabinet_door","tier":"easy","category":"furniture","score_baseline":0.964,"score_final":0.964,"passed":true,"rounds":1,"cost_usd":0.3002882,"minutes":4.14,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/articulated_v1_flash/runs/art_easy_cabinet_door","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}
+{"id":"art_easy_drawer_unit","tier":"easy","category":"furniture","score_baseline":0.988,"score_final":0.988,"passed":true,"rounds":1,"cost_usd":0.373319525,"minutes":5.29,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/articulated_v1_flash/runs/art_easy_drawer_unit","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}
diff --git a/harness/bench/out/static_v1_flash/battery.json b/harness/bench/out/static_v1_flash/battery.json
new file mode 100644
index 00000000..c5e935c4
--- /dev/null
+++ b/harness/bench/out/static_v1_flash/battery.json
@@ -0,0 +1,383 @@
+{
+ "battery": {
+ "name": "static_objects_v1",
+ "track": "static_object",
+ "language": "blender",
+ "description": "24 static-object prompts, 8 categories \u00d7 3 tiers (easy / medium / hard). Every prompt carries must_have items the planner turns into acceptance checks. Same battery runs under any generator; keep the judge model fixed across arms.\n",
+ "prompts": [
+ {
+ "id": "furn_easy_stool",
+ "prompt": "a simple three-legged round wooden stool, 45 cm tall",
+ "tier": "easy",
+ "category": "furniture",
+ "must_have": [
+ "round seat",
+ "three splayed legs of equal length",
+ "legs touch the ground"
+ ],
+ "dimensions_m": {
+ "height": 0.45
+ },
+ "tags": []
+ },
+ {
+ "id": "furn_med_dining_chair",
+ "prompt": "a mid-century wooden dining chair with a slatted backrest and tapered legs",
+ "tier": "medium",
+ "category": "furniture",
+ "must_have": [
+ "four tapered legs",
+ "seat slab",
+ "backrest with at least three vertical slats",
+ "back legs continue into back posts"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "furn_hard_rolltop_desk",
+ "prompt": "a writing desk with two pedestals of three drawers each, a central knee-hole, a leather inlay top and brass drawer pulls",
+ "tier": "hard",
+ "category": "furniture",
+ "must_have": [
+ "two drawer pedestals",
+ "three drawers per pedestal with visible fronts",
+ "knee-hole gap",
+ "brass pull handles",
+ "desk top overhangs"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "veh_easy_toy_car",
+ "prompt": "a chunky toy car with a rounded body and four thick wheels",
+ "tier": "easy",
+ "category": "vehicles",
+ "must_have": [
+ "one-piece rounded body",
+ "four wheels touching the ground",
+ "wheels protrude sideways"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "veh_med_pickup",
+ "prompt": "a pickup truck with a two-door cab, open cargo bed, wheel arches and side mirrors",
+ "tier": "medium",
+ "category": "vehicles",
+ "must_have": [
+ "cab with windows",
+ "open rear bed",
+ "four wheels with hubs",
+ "front grille and headlights",
+ "side mirrors"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "veh_hard_tractor",
+ "prompt": "a farm tractor with large rear tyres with treads, small front wheels, an exposed engine block, exhaust stack, driver seat, steering wheel and a roll bar",
+ "tier": "hard",
+ "category": "vehicles",
+ "must_have": [
+ "rear wheels much larger than front wheels",
+ "tyre tread detail",
+ "exhaust stack",
+ "seat and steering wheel",
+ "roll bar",
+ "engine hood"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "tool_easy_hammer",
+ "prompt": "a claw hammer with a wooden handle and a steel head",
+ "tier": "easy",
+ "category": "tools",
+ "must_have": [
+ "cylindrical handle",
+ "steel head with a flat face",
+ "forked claw on the back"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "tool_med_hand_drill",
+ "prompt": "a cordless power drill with a pistol grip, trigger, battery pack in the base of the grip and a keyless chuck holding a drill bit",
+ "tier": "medium",
+ "category": "tools",
+ "must_have": [
+ "pistol grip body",
+ "trigger",
+ "battery block under grip",
+ "chuck with a bit",
+ "side vents"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "tool_hard_bench_vise",
+ "prompt": "a cast-iron bench vise with fixed and sliding jaws, a lead screw with a tommy bar handle, guide rails, a small anvil face and mounting base with bolt holes",
+ "tier": "hard",
+ "category": "tools",
+ "must_have": [
+ "two jaws with a visible gap",
+ "sliding jaw on guide rails",
+ "lead screw with sliding T handle",
+ "anvil flat",
+ "base with bolt holes"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "appl_easy_kettle",
+ "prompt": "an electric kettle with a spout, a lid and a side handle on a round base",
+ "tier": "easy",
+ "category": "appliances",
+ "must_have": [
+ "pot body",
+ "pouring spout",
+ "handle opposite the spout",
+ "lid on top",
+ "round base"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "appl_med_toaster",
+ "prompt": "a two-slot retro toaster with rounded chrome body, a lever on the side, a browning dial and a crumb tray",
+ "tier": "medium",
+ "category": "appliances",
+ "must_have": [
+ "two bread slots on top",
+ "side lever",
+ "dial knob",
+ "rounded body",
+ "small feet"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "appl_hard_espresso",
+ "prompt": "an espresso machine with a group head and portafilter, a steam wand, a drip tray with grate, a water tank at the back, and a top-mounted cup warmer with a pressure gauge on the front panel",
+ "tier": "hard",
+ "category": "appliances",
+ "must_have": [
+ "portafilter with handle under a group head",
+ "steam wand on the side",
+ "drip tray with grate",
+ "water tank",
+ "pressure gauge",
+ "cup warmer rail"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "plant_easy_cactus",
+ "prompt": "a potted barrel cactus in a terracotta pot with soil",
+ "tier": "easy",
+ "category": "plants",
+ "must_have": [
+ "ribbed round cactus body",
+ "terracotta pot with rim",
+ "soil surface"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "plant_med_palm",
+ "prompt": "a small potted palm with a textured trunk and eight arching fronds made of many leaflets",
+ "tier": "medium",
+ "category": "plants",
+ "must_have": [
+ "textured trunk",
+ "at least eight fronds",
+ "fronds arch downward",
+ "leaflets along each frond",
+ "pot"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "plant_hard_bonsai",
+ "prompt": "a bonsai tree with a twisted thick trunk, three layered foliage pads, exposed roots over a rock and a shallow oval ceramic tray with moss",
+ "tier": "hard",
+ "category": "plants",
+ "must_have": [
+ "twisted trunk with taper",
+ "at least three distinct foliage pads",
+ "exposed roots gripping a rock",
+ "shallow oval tray",
+ "moss surface"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "bld_easy_shed",
+ "prompt": "a small garden shed with a pitched roof, one door and one window",
+ "tier": "easy",
+ "category": "buildings",
+ "must_have": [
+ "box walls",
+ "pitched roof overhang",
+ "door on front",
+ "window"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "bld_med_lighthouse",
+ "prompt": "a tapered lighthouse with red and white bands, a gallery with railing, a glass lantern room and a domed cap, on a rocky base",
+ "tier": "medium",
+ "category": "buildings",
+ "must_have": [
+ "tapered tower",
+ "alternating bands",
+ "gallery walkway with railing",
+ "glass lantern room",
+ "dome",
+ "rock base"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "bld_hard_windmill",
+ "prompt": "a Dutch windmill with an octagonal tapered body, thatched cap, four lattice sails, a balcony stage with railing, a door, and two shuttered windows",
+ "tier": "hard",
+ "category": "buildings",
+ "must_have": [
+ "octagonal tapered body",
+ "cap",
+ "four lattice sails in a cross",
+ "balcony with railing",
+ "door",
+ "shuttered windows"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "toy_easy_blocks",
+ "prompt": "a stack of five alphabet blocks of decreasing size in a slightly twisted tower",
+ "tier": "easy",
+ "category": "toys",
+ "must_have": [
+ "five cubes",
+ "decreasing size upward",
+ "each slightly rotated",
+ "all stacked touching"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "toy_med_rocking_horse",
+ "prompt": "a wooden rocking horse with curved rockers, a saddle, handles and a mane",
+ "tier": "medium",
+ "category": "toys",
+ "must_have": [
+ "horse body with head and four legs",
+ "two curved rockers",
+ "saddle",
+ "handle grips",
+ "mane"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "toy_hard_train",
+ "prompt": "a toy steam locomotive with a boiler, smokestack, cab with windows, cowcatcher, six driving wheels with connecting rods, and a coal tender with four wheels",
+ "tier": "hard",
+ "category": "toys",
+ "must_have": [
+ "cylindrical boiler",
+ "smokestack",
+ "cab",
+ "cowcatcher",
+ "six large wheels with rods",
+ "separate tender with coal load and four wheels"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "mus_easy_drum",
+ "prompt": "a snare drum with tension rods and two drumsticks resting on top",
+ "tier": "easy",
+ "category": "musical_instruments",
+ "must_have": [
+ "cylindrical shell",
+ "top head",
+ "at least eight tension rods around the rim",
+ "two sticks"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "mus_med_acoustic_guitar",
+ "prompt": "an acoustic guitar with a figure-eight body, sound hole, bridge, fretted neck, headstock with six tuning pegs and six strings",
+ "tier": "medium",
+ "category": "musical_instruments",
+ "must_have": [
+ "figure-eight body",
+ "sound hole",
+ "bridge",
+ "neck with frets",
+ "headstock",
+ "six tuning pegs",
+ "six strings"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ },
+ {
+ "id": "mus_hard_drum_kit",
+ "prompt": "a five-piece drum kit with a bass drum with pedal, snare on a stand, two rack toms, a floor tom, a hi-hat and two cymbals on stands, and a throne",
+ "tier": "hard",
+ "category": "musical_instruments",
+ "must_have": [
+ "bass drum with pedal",
+ "snare on stand",
+ "two mounted toms",
+ "floor tom with legs",
+ "hi-hat with two cymbals",
+ "two crash/ride cymbals on stands",
+ "drum throne"
+ ],
+ "dimensions_m": null,
+ "tags": []
+ }
+ ]
+ },
+ "options": {
+ "generator": "api-agent:gemini:gemini-3.7-flash",
+ "planner": null,
+ "judge": "gemini:gemini-3.1-pro-preview",
+ "rounds": 3,
+ "max_usd": 2.0,
+ "max_minutes": 60.0,
+ "parallel": 4,
+ "limit": null,
+ "ids": [],
+ "tiers": [],
+ "resume": true
+ },
+ "started_at": "2026-08-23T11:10:43.831385+00:00"
+}
\ No newline at end of file
diff --git a/harness/bench/out/static_v1_flash/results.jsonl b/harness/bench/out/static_v1_flash/results.jsonl
new file mode 100644
index 00000000..c6180b1c
--- /dev/null
+++ b/harness/bench/out/static_v1_flash/results.jsonl
@@ -0,0 +1,5 @@
+{"id":"furn_med_dining_chair","tier":"medium","category":"furniture","score_baseline":null,"score_final":null,"passed":null,"rounds":0,"cost_usd":0.0,"minutes":0.92,"status":"error","errors":"ModelError: Gemini API error 503: This model is currently experiencing high demand. Spikes in demand are usually temporary. Please try again later.\nl=self.plan_model)\n ^^^^^^^^^^^^^^^^^^^^^^\n File \"/home/yipeng/3dcodeverse/harness/codeverse/orchestrator/runner.py\", line 91, in stage\n result = fn()\n File \"/home/yipeng/3dcodeverse/harness/codeverse/tracks/lifecycle.py\", line 147, in <lambda>\n ctx.plan = runner.stage(\"plan\", lambda: self._plan_stage(ctx), inputs={\"spec\": plan_stage_inputs(spec), \"track\": self.track.value},\n ~~~~~~~~~~~~~~~~^^^^^\n File \"/home/yipeng/3dcodeverse/harness/codeverse/tracks/lifecycle.py\", line 230, in _plan_stage\n plan = run_planner(ctx.spec, ctx.spec.backends.planner, self.plan_model, ctx.ws, model=self._planner_model,\n events=ctx.events, budget=ctx.budget, runtime=ctx.runtime)\n File \"/home/yipeng/3dcodeverse/harness/codeverse/tracks/planner.py\", line 48, in plan\n result, usage = plan_with_usage(spec, model_id, plan_model, ws, model=model, events=events, runtime=runtime)\n ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n File \"/home/yipeng/3dcodeverse/harness/codeverse/tracks/planner.py\", line 70, in plan_with_usage\n resp = model.generate(req)\n File \"/home/yipeng/3dcodeverse/harness/codeverse/models/gemini.py\", line 257, in generate\n raise err from exc\ncodeverse.models.base.ModelError: Gemini API error 503: This model is currently experiencing high demand. Spikes in demand are usually temporary. Please try again later.\n","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/furn_med_dining_chair","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}
+{"id":"furn_easy_stool","tier":"easy","category":"furniture","score_baseline":0.75,"score_final":0.75,"passed":true,"rounds":1,"cost_usd":0.30198767499999996,"minutes":4.46,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/furn_easy_stool","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}
+{"id":"veh_easy_toy_car","tier":"easy","category":"vehicles","score_baseline":0.282,"score_final":0.85,"passed":true,"rounds":3,"cost_usd":1.6814668499999998,"minutes":20.78,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/veh_easy_toy_car","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}
+{"id":"furn_hard_rolltop_desk","tier":"hard","category":"furniture","score_baseline":0.7,"score_final":0.75,"passed":true,"rounds":3,"cost_usd":1.2165176,"minutes":22.52,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/furn_hard_rolltop_desk","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}
+{"id":"tool_easy_hammer","tier":"easy","category":"tools","score_baseline":0.944,"score_final":0.944,"passed":true,"rounds":1,"cost_usd":0.40064702500000005,"minutes":5.59,"status":"passed","errors":"","workspace":"/home/yipeng/3dcodeverse/harness/bench/out/static_v1_flash/runs/tool_easy_hammer","generator":"api-agent:gemini:gemini-3.7-flash","judge":"gemini:gemini-3.1-pro-preview"}
diff --git a/harness/codeverse/config.py b/harness/codeverse/config.py
index 57baa80c..3f23f969 100644
--- a/harness/codeverse/config.py
+++ b/harness/codeverse/config.py
@@ -20,6 +20,8 @@ import yaml
from pydantic import BaseModel, Field
from pydantic_settings import BaseSettings, SettingsConfigDict
+from codeverse.contracts.common import Backends
+
_LEGACY_KEYS_FILE = Path.home() / ".config" / "astra3d" / "gemini_keys.env"
_USER_CONFIG = Path.home() / ".config" / "codeverse" / "config.yaml"
@@ -67,14 +69,33 @@ class Settings(BaseSettings):
openai_api_key: str = ""
openai_base_url: str = ""
- default_planner: str = "gemini:gemini-3.7-flash"
- default_generator: str = "api-agent:gemini:gemini-3.7-flash"
- # The judge drives the refine loop: the pro tier has ~3x lower sample noise than flash
- # (calibration 2026-08-23: std 0.03 vs 0.08-0.12) for ~$0.07 per verdict.
- default_judge: str = "gemini:gemini-3.1-pro-preview"
+ # Backend-role defaults: the literals live in ONE place — contracts/common.py::Backends
+ # (which also documents why the judge default is the pro tier).
+ default_planner: str = Field(default_factory=lambda: Backends().planner)
+ default_generator: str = Field(default_factory=lambda: Backends().generator)
+ default_judge: str = Field(default_factory=lambda: Backends().judge)
+ default_captioner: str = Field(default_factory=lambda: Backends().captioner)
default_candidates: int = Field(default=1, description="best-of-N baseline candidates (tracks read it)")
# ------------------------------------------------------------------ helpers
+ def backends(self, **overrides: str | None) -> Backends:
+ """The ``Backends`` for a new Spec from the settings defaults. Keyword
+ overrides (``planner`` / ``generator`` / ``judge`` / ``captioner``) win
+ when truthy; ``None`` / ``""`` falls through to the default."""
+ base: dict[str, str] = {
+ "planner": self.default_planner,
+ "generator": self.default_generator,
+ "judge": self.default_judge,
+ "captioner": self.default_captioner,
+ }
+ unknown = set(overrides) - set(base)
+ if unknown:
+ raise TypeError(f"unknown backend role(s): {sorted(unknown)} (roles: {sorted(base)})")
+ for role, value in overrides.items():
+ if value:
+ base[role] = value
+ return Backends(**base)
+
def resolve_blender(self) -> str:
if self.binaries.blender and Path(self.binaries.blender).exists():
return self.binaries.blender
diff --git a/harness/codeverse/contracts/__init__.py b/harness/codeverse/contracts/__init__.py
index 01cb2c65..376dda8f 100644
--- a/harness/codeverse/contracts/__init__.py
+++ b/harness/codeverse/contracts/__init__.py
@@ -11,7 +11,7 @@ Modules:
- ``agent`` CodingAgent job/result shapes.
"""
-from codeverse.contracts.agent import AgentJob, AgentResult, FileChange
+from codeverse.contracts.agent import AgentJob, AgentResult, ApiAgentOptions, FileChange
from codeverse.contracts.artifacts import (
BuildResult,
GateFinding,
@@ -32,7 +32,20 @@ from codeverse.contracts.chat import (
ToolResultPart,
ToolSpec,
)
-from codeverse.contracts.common import Backends, Budget, Language, Track, Usage, Vec3
+from codeverse.contracts.common import (
+ ENTRY_FILE,
+ LANGUAGE_LABEL,
+ TRACK_INFO,
+ TRACK_LANGUAGES,
+ Backends,
+ Budget,
+ Language,
+ Track,
+ TrackInfo,
+ Usage,
+ Vec3,
+ code_file,
+)
from codeverse.contracts.judgment import ImprovementItem, JudgeIssue, Judgment
from codeverse.contracts.plan import (
AcceptanceItem,
@@ -51,6 +64,6 @@ from codeverse.contracts.plan import (
ZonePlan,
)
from codeverse.contracts.run import RoundRecord, RunRecord, RunStatus
-from codeverse.contracts.spec import Constraints, ReferenceImage, Spec
+from codeverse.contracts.spec import Constraints, ReferenceImage, RunOptions, Spec
__all__ = [name for name in dir() if not name.startswith("_")]
diff --git a/harness/codeverse/contracts/agent.py b/harness/codeverse/contracts/agent.py
index 82a3ecd2..19ed0bb3 100644
--- a/harness/codeverse/contracts/agent.py
+++ b/harness/codeverse/contracts/agent.py
@@ -4,7 +4,7 @@ from __future__ import annotations
from typing import Any
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
from codeverse.contracts.common import Usage
@@ -16,6 +16,20 @@ class FileChange(BaseModel):
lines_removed: int = 0
+class ApiAgentOptions(BaseModel):
+ """Knobs honoured only by the in-process ``api-agent`` backend."""
+
+ max_usd: float = Field(default=0.0, description="stop the session when its own cost exceeds this (0 = no cap)")
+ temperature: float = 0.3
+ thinking: str = "low"
+ allow_shell: bool = True
+
+
+#: legacy ``AgentJob.extra`` keys lifted into the typed fields (values stay in extra too)
+_LEGACY_JOB_KEYS = ("round", "kind", "language", "track", "files_hint", "mcp_command")
+_LEGACY_API_KEYS = ("max_usd", "temperature", "thinking", "allow_shell")
+
+
class AgentJob(BaseModel):
workspace: str
prompt: str
@@ -28,7 +42,40 @@ class AgentJob(BaseModel):
spatial_tools: bool = Field(default=True, description="expose the 3dcv MCP spatial tools to the agent")
write_roots: list[str] = Field(default_factory=lambda: ["src", "public"], description="dirs the agent may edit")
env: dict[str, str] = Field(default_factory=dict)
- extra: dict[str, Any] = Field(default_factory=dict)
+ # ------------------------------------------------------------- typed job context
+ round: int = Field(default=0, description="round index → trajectory dir + ToolContext")
+ kind: str = Field(default="", description="task kind: baseline | refine | repair | asset | zone ...")
+ language: str = Field(default="", description="spec language (spatial tool filtering)")
+ track: str = Field(default="", description="spec track (spatial tool filtering)")
+ files_hint: list[str] = Field(
+ default_factory=list,
+ description="workspace-relative files/dirs this task is expected to touch — attributes "
+ "files_changed between concurrent sessions in one workspace",
+ )
+ mcp_command: list[str] | None = Field(default=None, description="override for the 3dcv MCP server command")
+ api: ApiAgentOptions = Field(default_factory=ApiAgentOptions)
+ extra: dict[str, Any] = Field(default_factory=dict, description="one-off backend hints (legacy keys are lifted)")
+
+ @model_validator(mode="before")
+ @classmethod
+ def _lift_legacy_extra(cls, data: Any) -> Any:
+ """Constructors that pass ``extra={"round": 2, ...}`` keep working: known keys
+ are lifted into the typed fields. ``extra`` itself is left untouched so
+ existing ``job.extra[...]`` readers see exactly what they were given."""
+ if not isinstance(data, dict):
+ return data
+ extra = data.get("extra")
+ if not isinstance(extra, dict):
+ return data
+ data = dict(data) # never mutate the caller's dict
+ for key in _LEGACY_JOB_KEYS:
+ if key in extra and key not in data:
+ data[key] = extra[key]
+ if "api" not in data:
+ lifted = {k: extra[k] for k in _LEGACY_API_KEYS if k in extra}
+ if lifted:
+ data["api"] = lifted
+ return data
class AgentResult(BaseModel):
diff --git a/harness/codeverse/contracts/artifacts.py b/harness/codeverse/contracts/artifacts.py
index 10e06325..5fa6b5b9 100644
--- a/harness/codeverse/contracts/artifacts.py
+++ b/harness/codeverse/contracts/artifacts.py
@@ -24,6 +24,31 @@ class GateFinding(BaseModel):
fix_hint: str = Field(default="", description="concrete, copyable instruction for the fixer")
data: dict[str, Any] = Field(default_factory=dict)
+ def as_line(
+ self,
+ *,
+ with_gate: bool = False,
+ with_severity: bool = False,
+ with_target: bool = False,
+ with_hint: bool = True,
+ ) -> str:
+ """One presentation line for prompts/reports — no leading ``- `` (callers
+ own their list bullets). ``message`` is always present; the flags opt in
+ to a ``GATE <gate>:`` prefix, a ``[<severity>]`` tag, a `` [<target>]``
+ suffix and the `` FIX: <fix_hint>`` suffix (default on, when non-empty)."""
+ parts: list[str] = []
+ if with_gate:
+ parts.append(f"GATE {self.gate}:")
+ if with_severity:
+ parts.append(f"[{self.severity.value}]")
+ parts.append(self.message)
+ line = " ".join(parts)
+ if with_target and self.target:
+ line += f" [{self.target}]"
+ if with_hint and self.fix_hint:
+ line += f" FIX: {self.fix_hint}"
+ return line
+
class GateReport(BaseModel):
gate: str
@@ -91,6 +116,10 @@ class RenderView(BaseModel):
look_at: Vec3 | None = None
fov: float | None = None
time_s: float | None = Field(default=None, description="animation time for scenes")
+ judge: bool | None = Field(
+ default=None,
+ description="True/False once the judge subset is stamped at render time; None = not stamped (legacy rounds)",
+ )
class RenderSet(BaseModel):
@@ -101,3 +130,4 @@ class RenderSet(BaseModel):
duration_ms: int = 0
console_errors: list[str] = Field(default_factory=list, description="(scenes) JS/WebGL errors seen")
fps: float | None = None
+ out_dir: str = Field(default="", description="directory the views (+ views.json/metrics.json) were written to")
diff --git a/harness/codeverse/contracts/common.py b/harness/codeverse/contracts/common.py
index e1a280c2..86258f22 100644
--- a/harness/codeverse/contracts/common.py
+++ b/harness/codeverse/contracts/common.py
@@ -5,7 +5,7 @@ from __future__ import annotations
from enum import StrEnum
from typing import Annotated
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
Vec3 = Annotated[tuple[float, float, float], Field(description="x, y, z")]
@@ -40,6 +40,58 @@ TRACK_LANGUAGES: dict[Track, tuple[Language, ...]] = {
}
+class TrackInfo(BaseModel):
+ """Per-track registry row: default judge rubric + human label.
+
+ THE single source for what used to be restated as ``TRACK_RUBRIC`` /
+ ``RUBRIC_BY_TRACK`` / ``TYPE_LABEL`` in judges, texturing, flywheel and cli.
+ """
+
+ model_config = ConfigDict(frozen=True)
+
+ rubric: str = Field(description="rubric name under judges/rubrics/, e.g. 'static_object_v1'")
+ label: str = Field(description="human label for galleries / captions / reports")
+
+
+#: one registry row per track
+TRACK_INFO: dict[Track, TrackInfo] = {
+ Track.STATIC_OBJECT: TrackInfo(rubric="static_object_v1", label="3D Objects"),
+ Track.ARTICULATED_OBJECT: TrackInfo(rubric="articulated_v1", label="Articulated Objects"),
+ Track.SCENE: TrackInfo(rubric="scene_v1", label="3D Scenes"),
+ Track.GRAPHICS: TrackInfo(rubric="shader_v1", label="Procedural Graphics"),
+}
+
+#: entry file inside the workspace per language — the file a build starts from.
+#: THE single source for entry paths (runtimes' first entry_glob, flywheel export).
+ENTRY_FILE: dict[Language, str] = {
+ Language.BLENDER: "src/model.py",
+ Language.CADQUERY: "src/model.py",
+ Language.URDF_BLENDER: "src/model.py",
+ Language.THREEJS: "src/object.js",
+ Language.SCENE_THREEJS: "src/scene.js",
+ Language.GLSL_SHADER: "src/shader.frag",
+ Language.OPENGL_PYTHON: "src/program.py",
+}
+
+#: human label per language (galleries, captions, reports)
+LANGUAGE_LABEL: dict[Language, str] = {
+ Language.BLENDER: "Blender Python",
+ Language.CADQUERY: "CadQuery (Python)",
+ Language.URDF_BLENDER: "URDF + Blender Python",
+ Language.THREEJS: "Three.js (ESM)",
+ Language.SCENE_THREEJS: "Three.js scene (multi-file ESM + GLSL)",
+ Language.GLSL_SHADER: "GLSL fragment shader",
+ Language.OPENGL_PYTHON: "OpenGL (moderngl Python + GLSL)",
+}
+
+
+def code_file(language: Language) -> str:
+ """Top-level flywheel copy of the entry file: ``code`` + the entry suffix
+ (``code.py`` / ``code.js`` / ``code.frag``)."""
+ entry = ENTRY_FILE[language]
+ return "code" + entry[entry.rfind(".") :]
+
+
class Usage(BaseModel):
"""Normalised token/cost accounting for ONE model or agent call."""
@@ -88,5 +140,7 @@ class Backends(BaseModel):
planner: str = "gemini:gemini-3.7-flash"
generator: str = "api-agent:gemini:gemini-3.7-flash"
+ # The judge drives the refine loop: the pro tier has ~3x lower sample noise than
+ # flash (calibration 2026-08-23: std 0.03 vs 0.08-0.12) for ~$0.07 per verdict.
judge: str = "gemini:gemini-3.1-pro-preview"
captioner: str = "gemini:gemini-3.7-flash"
diff --git a/harness/codeverse/contracts/spec.py b/harness/codeverse/contracts/spec.py
index dac2a5f8..7665922e 100644
--- a/harness/codeverse/contracts/spec.py
+++ b/harness/codeverse/contracts/spec.py
@@ -28,6 +28,17 @@ class Constraints(BaseModel):
must_not: list[str] = Field(default_factory=list)
+class RunOptions(BaseModel):
+ """Run-shape options frozen on the spec (distinct from Budget and Backends).
+
+ ``None`` / ``False`` means "not stated": resolution falls through to
+ ``run_state.extra`` (legacy runs) and then ``Settings`` defaults.
+ """
+
+ candidates: int | None = Field(default=None, ge=1, description="best-of-N baseline candidates")
+ texture: bool = Field(default=False, description="run the derived texture pass after the loop")
+
+
class Spec(BaseModel):
id: str
track: Track
@@ -37,6 +48,7 @@ class Spec(BaseModel):
constraints: Constraints = Field(default_factory=Constraints)
budget: Budget = Field(default_factory=Budget)
backends: Backends = Field(default_factory=Backends)
+ options: RunOptions = Field(default_factory=RunOptions)
seed: int = 0
tags: list[str] = Field(default_factory=list)
created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
diff --git a/harness/codeverse/conventions.py b/harness/codeverse/conventions.py
index 7db79d08..f1258c3c 100644
--- a/harness/codeverse/conventions.py
+++ b/harness/codeverse/conventions.py
@@ -9,6 +9,8 @@ Frames
* ``blender`` / ``cadquery`` / ``urdf``: **Z-up, -Y is the object's front**,
meters. (Blender's "Front" view looks along +Y, so a front face points -Y.)
* ``threejs`` / ``scene_threejs``: **Y-up, +Z is the front**, meters.
+* ``glsl_shader`` / ``opengl_python``: **Y-up, +Z front** (GL clip space is
+ Y-up; harness cameras/gates treat graphics output like the three.js frame).
* Canonical exchange format is **GLB (glTF 2.0): Y-up, +Z front, meters**.
Blender's glTF exporter maps (x, y, z) → (x, z, -y), so a Blender -Y front
becomes glTF +Z front — the two native frames agree once exported.
@@ -45,6 +47,9 @@ LANGUAGE_FRAME: dict[str, Frame] = {
"urdf_blender": Frame.Z_UP_NEG_Y_FRONT,
"threejs": Frame.Y_UP_POS_Z_FRONT,
"scene_threejs": Frame.Y_UP_POS_Z_FRONT,
+ # GL clip space is Y-up: graphics output is framed like the three.js/glTF frame.
+ "glsl_shader": Frame.Y_UP_POS_Z_FRONT,
+ "opengl_python": Frame.Y_UP_POS_Z_FRONT,
}
GLB_FRAME = Frame.Y_UP_POS_Z_FRONT
diff --git a/harness/codeverse/proc.py b/harness/codeverse/proc.py
new file mode 100644
index 00000000..0110e391
--- /dev/null
+++ b/harness/codeverse/proc.py
@@ -0,0 +1,99 @@
+"""Subprocess + atomic-JSON primitives shared across the harness.
+
+One home for the run-a-child-process pattern (own process group, wall-clock
+timeout, group kill, captured output) and the tmp+rename JSON write. Peer of
+``workspace.py``; stdlib-only — imports nothing from ``codeverse`` so wrappers,
+spatial helpers and agents can all use it without layering back-edges.
+
+``languages/_common.py`` currently carries the same helpers for its runtime
+callers; it will become a re-export of this module.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ProcResult:
+ """Outcome of one subprocess run."""
+
+ returncode: int
+ stdout: str
+ stderr: str
+ timed_out: bool
+ duration_ms: int
+
+
+def run_subprocess(
+ cmd: list[str],
+ *,
+ cwd: Path | str,
+ timeout_s: float,
+ env: Mapping[str, str] | None = None,
+ stdin_text: str | None = None,
+ preexec_fn: Callable[[], None] | None = None,
+) -> ProcResult:
+ """Run ``cmd`` in its own process group; kill the whole group on timeout.
+
+ Never raises on non-zero exit — callers inspect :attr:`ProcResult.returncode`.
+ ``preexec_fn`` runs in the child before exec (e.g. rlimits); the child is
+ always started in a new session so :func:`kill_group` reaps grandchildren.
+ """
+ t0 = time.monotonic()
+ proc = subprocess.Popen(
+ cmd,
+ cwd=str(cwd),
+ env=dict(env) if env is not None else None,
+ stdin=subprocess.PIPE if stdin_text is not None else subprocess.DEVNULL,
+ stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE,
+ text=True,
+ start_new_session=True,
+ preexec_fn=preexec_fn,
+ )
+ timed_out = False
+ try:
+ out, err = proc.communicate(input=stdin_text, timeout=timeout_s)
+ except subprocess.TimeoutExpired:
+ timed_out = True
+ kill_group(proc)
+ out, err = proc.communicate()
+ return ProcResult(
+ returncode=proc.returncode if proc.returncode is not None else -1,
+ stdout=out or "",
+ stderr=err or "",
+ timed_out=timed_out,
+ duration_ms=int((time.monotonic() - t0) * 1000),
+ )
+
+
+def kill_group(proc: subprocess.Popen[str]) -> None:
+ """SIGKILL ``proc``'s whole process group (fall back to just the child)."""
+ try:
+ os.killpg(proc.pid, signal.SIGKILL)
+ except (ProcessLookupError, PermissionError):
+ proc.kill()
+
+
+def tail(text: str, *, max_lines: int = 40, max_chars: int = 4000) -> str:
+ """Last ``max_lines`` lines of ``text``, capped at ``max_chars`` characters."""
+ lines = text.splitlines()[-max_lines:]
+ s = "\n".join(lines)
+ return s[-max_chars:] if len(s) > max_chars else s
+
+
+def write_json_atomic(path: Path, data: Any) -> None:
+ """tmp + rename so readers never see a partial file."""
+ path.parent.mkdir(parents=True, exist_ok=True)
+ tmp = path.with_suffix(path.suffix + ".tmp")
+ tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False, default=str))
+ tmp.replace(path)
diff --git a/harness/codeverse/workspace.py b/harness/codeverse/workspace.py
index 576312a5..e35a6e79 100644
--- a/harness/codeverse/workspace.py
+++ b/harness/codeverse/workspace.py
@@ -19,6 +19,7 @@ from typing import Any
from pydantic import BaseModel
from codeverse.contracts.agent import FileChange
+from codeverse.proc import write_json_atomic
_DIRS = ("src", "public", "artifacts", "artifacts/renders", "artifacts/gates", "artifacts/judge", "trajectories")
@@ -92,12 +93,9 @@ class Workspace:
# ----------------------------------------------------------------- json io
def write_json(self, path: Path, model: BaseModel | dict[str, Any]) -> None:
- """Atomic JSON write (tmp + rename)."""
- path.parent.mkdir(parents=True, exist_ok=True)
- tmp = path.with_suffix(path.suffix + ".tmp")
+ """Atomic JSON write (tmp + rename, via :func:`codeverse.proc.write_json_atomic`)."""
data = model.model_dump(mode="json") if isinstance(model, BaseModel) else model
- tmp.write_text(json.dumps(data, indent=2, ensure_ascii=False))
- tmp.replace(path)
+ write_json_atomic(path, data)
def read_json(self, path: Path) -> dict[str, Any]:
return json.loads(path.read_text())
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index dea8e564..1738f9b7 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -68,11 +68,16 @@ the flywheel unit.
codeverse/
conventions.py frames (LANGUAGE_FRAME, GLB_FRAME), units, OBJECT_VIEWS/_QUICK, SCENE_VIEWS,
to_snake/to_pascal/slugify, MAX_TRIS_*, BBOX_TOLERANCE_M, CONTACT_GAP_M (THE source)
- config.py Settings (CV3D_* env, ~/.config/codeverse/config.yaml; default_judge=gemini-3.1-pro-preview,
+ config.py Settings (CV3D_* env, ~/.config/codeverse/config.yaml; role defaults come from
+ contracts Backends; Settings.backends(**overrides) builds a Spec's Backends;
default_candidates=1)
- contracts/ pydantic: common (Track, Language, Usage, Budget, Backends), spec, plan, artifacts,
- judgment, run, chat, agent
+ contracts/ pydantic: common (Track, Language, Usage, Budget, Backends, TRACK_INFO registry,
+ ENTRY_FILE/code_file/LANGUAGE_LABEL tables), spec (+ RunOptions), plan, artifacts
+ (GateFinding.as_line, RenderView.judge, RenderSet.out_dir), judgment, run, chat,
+ agent (typed AgentJob + ApiAgentOptions)
workspace.py run-dir layout + git snapshots ; events.py JSONL event log
+ proc.py stdlib-only subprocess + atomic-JSON primitives (run_subprocess w/ group kill +
+ preexec_fn, kill_group, tail, write_json_atomic) — shared by languages/spatial/cli
models/ ChatModel; gemini.py (dead-key + free 429 rotation), gemini_image.py (ImageModel),
anthropic.py openai.py, keypool.py ('dead' outcome), pricing.py (version-suffix-only
fallback), retry.py, schema_utils.py (strict schema: no null-for-default), registry.py
@@ -283,10 +288,7 @@ $0.02–0.03 (flash) / ~$0.2 (pro); api-agent generation 3–6 min per object ro
`n_samples ≥ 3` for decisions. Detail crops are position-heuristic (no 2D part
boxes yet).
* `scene_frames` gate + judge-view subset are built (renders side) but not yet
- wired into the scene track; `conventions.LANGUAGE_FRAME` lacks
- glsl_shader/opengl_python entries (stopgap `setdefault` in `tracks/graphics.py`);
- `3dcv judge` lacks a GRAPHICS → shader_v1 mapping; `flywheel export` lacks
- graphics entry-file mappings.
+ wired into the scene track.
* Articulated: candidate selection uses the quick 4-view sheet (not pose views);
mimic joints ignored; sweep is O(links² × poses).
* Scenes: fps is a relative cost; camera-in-geometry can miss open-back enclosures.
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 88c7ff8e..a17ca2ea 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -20,6 +20,27 @@ file was reconciled against it on 2026-08-23 (waves 2–3 + fix batch 1).
`gemini-3.1-flash-image`, fallback `gemini-2.5-flash-image`) behind the
`ImageModel` protocol (`generate`, `generate_with_usage` → `(images, Usage)`).
+## core (contracts · config · proc)
+
+```python
+from codeverse.contracts import TRACK_INFO, TrackInfo # {Track: TrackInfo(rubric, label)} — THE track registry
+from codeverse.contracts import ENTRY_FILE, code_file, LANGUAGE_LABEL # {Language: "src/<entry>"}; code_file(lang) -> "code.<ext>"
+from codeverse.contracts import RunOptions # Spec.options: candidates (int|None, ≥1), texture (bool)
+GateFinding.as_line(with_gate=False, with_severity=False, with_target=False, with_hint=True) -> str
+ # "GATE <gate>: [<sev>] <message> [<target>] FIX: <hint>" — flags opt in; no leading "- "
+RenderView.judge: bool | None # stamped True/False at render time; None = legacy round (fall back to select_judge_views)
+RenderSet.out_dir: str # directory the views (+ views.json/metrics.json) were written to ("" on old rounds)
+from codeverse.config import get_settings
+get_settings().backends(planner=..., generator=..., judge=..., captioner=...) -> Backends
+ # settings defaults (default_planner/... mirror contracts Backends literals; + default_captioner);
+ # truthy keyword overrides win, None/"" falls through, unknown role -> TypeError
+from codeverse.proc import ProcResult, run_subprocess, kill_group, tail, write_json_atomic
+run_subprocess(cmd, *, cwd, timeout_s, env=None, stdin_text=None, preexec_fn=None) -> ProcResult
+ # own session/process group, group-kill on timeout, never raises on rc != 0; stdlib-only module
+```
+`Spec.options` is plan-hash safe (`plan_stage_inputs` whitelists spec fields).
+`Workspace.write_json` delegates to `proc.write_json_atomic`.
+
## models/
```python
from codeverse.models import get_chat_model # (model_id) -> ChatModel, lru-cached, thread-safe
@@ -73,11 +94,14 @@ res = agent.run(AgentJob(workspace=..., prompt=..., label="baseline", timeout_s=
res.ok, res.exit_reason # completed | timeout | error | budget | model_substituted
res.files_changed (git-derived, attributed per session), res.usage, res.transcript_path, res.tool_calls, res.errors
```
-`AgentJob.extra` keys honoured by every agent: `round`, `kind`, `language`, `track`,
-`mcp_command` (override), `max_usd` / `temperature` / `thinking` / `allow_shell`
-(api-agent only), **Δ `files_hint`** (list of workspace-relative files/dirs the task
-is expected to touch — used to attribute `files_changed` between concurrent sessions
-in one workspace; harness-owned paths and sibling sessions' hinted files are dropped).
+`AgentJob` carries typed job context: `round`, `kind`, `language`, `track`,
+`mcp_command` (override), `files_hint` (workspace-relative files/dirs the task is
+expected to touch — used to attribute `files_changed` between concurrent sessions in
+one workspace; harness-owned paths and sibling sessions' hinted files are dropped)
+and `job.api: ApiAgentOptions(max_usd, temperature, thinking, allow_shell)` (api-agent
+only). **Δ legacy lift**: the same keys passed inside `extra={...}` are lifted into
+the typed fields at validation (extra itself is left untouched), so old constructors
+and serialized jobs keep working; `extra` stays for one-off backend hints.
Trajectories: `ws/trajectories/<label>_rNN/{prompt.md, transcript.jsonl, stdout.json,
stderr.log, result.json}`; **Δ** a re-run of the same label+round lands in
`<label>.a2_rNN` (then `.a3` …) — the first attempt is never overwritten; `result.json`
diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.md
index dcfd244e..c5f5c343 100644
--- a/harness/docs/RUNBOOK.md
+++ b/harness/docs/RUNBOOK.md
@@ -160,13 +160,14 @@ Protocol and judge calibration: `docs/EVAL.md`.
## 8. Extending (plugin paths)
-* **New language**: enum in `contracts/common.py::Language` (+ `TRACK_LANGUAGES`),
- frame in `conventions.LANGUAGE_FRAME`; `languages/<lang>/{runtime.py, lint.py,
- skeleton.py, CONTRACT.md, wrappers/}` implementing `LanguageRuntime`; branch in
- `languages/base.py::get_runtime`; `prompts/<lang>/contract.md` + `cookbook.md`
- (every snippet must run — `tests/prompts` executes them); entry-file mappings in
- `flywheel/sample.py`; part→file mapping via `runtime.file_for_part` (blender and
- threejs have it; `tracks/prompting.file_for_target_factory` picks it up).
+* **New language**: enum in `contracts/common.py::Language` (+ `TRACK_LANGUAGES`,
+ `ENTRY_FILE`, `LANGUAGE_LABEL`), frame in `conventions.LANGUAGE_FRAME`;
+ `languages/<lang>/{runtime.py, lint.py, skeleton.py, CONTRACT.md, wrappers/}`
+ implementing `LanguageRuntime`; branch in `languages/base.py::get_runtime`;
+ `prompts/<lang>/contract.md` + `cookbook.md` (every snippet must run —
+ `tests/prompts` executes them); part→file mapping via `runtime.file_for_part`
+ (blender and threejs have it; `tracks/prompting.file_for_target_factory` picks
+ it up).
* **New spatial tool**: pydantic args + `@tool("name", Args, "…", tracks=(…),
languages=(…), cost_hint=…)` in `spatial/tools*.py` (imported from
`spatial/tools.py`); available to tracks, MCP, api-agent and prompt cards at once.
diff --git a/harness/tests/core/test_config_backends.py b/harness/tests/core/test_config_backends.py
new file mode 100644
index 00000000..ce51c726
--- /dev/null
+++ b/harness/tests/core/test_config_backends.py
@@ -0,0 +1,43 @@
+"""Settings.backends() — one source of backend-role defaults (Batch-1)."""
+
+from __future__ import annotations
+
+import pytest
+
+from codeverse.config import Settings
+from codeverse.contracts.common import Backends
+
+
+def test_settings_defaults_mirror_backends():
+ s = Settings()
+ assert s.backends() == Backends()
+ assert s.default_planner == Backends().planner
+ assert s.default_generator == Backends().generator
+ assert s.default_judge == Backends().judge
+ assert s.default_captioner == Backends().captioner
+
+
+def test_settings_overrides_flow_through():
+ s = Settings(default_generator="single-shot:gemini:gemini-3.7-flash", default_captioner="gemini:x")
+ b = s.backends()
+ assert b.generator == "single-shot:gemini:gemini-3.7-flash"
+ assert b.captioner == "gemini:x"
+ assert b.planner == Backends().planner
+
+
+def test_backends_keyword_overrides_win_when_truthy():
+ s = Settings()
+ b = s.backends(judge="gemini:custom", planner=None, generator="")
+ assert b.judge == "gemini:custom"
+ assert b.planner == Backends().planner # None falls through
+ assert b.generator == Backends().generator # "" falls through
+
+
+def test_backends_rejects_unknown_role():
+ with pytest.raises(TypeError, match="unknown backend role"):
+ Settings().backends(judger="x")
+
+
+def test_env_override_still_wins(monkeypatch):
+ monkeypatch.setenv("CV3D_DEFAULT_CAPTIONER", "gemini:from-env")
+ assert Settings().backends().captioner == "gemini:from-env"
diff --git a/harness/tests/core/test_contract_additions.py b/harness/tests/core/test_contract_additions.py
new file mode 100644
index 00000000..8ee930f3
--- /dev/null
+++ b/harness/tests/core/test_contract_additions.py
@@ -0,0 +1,160 @@
+"""Batch-1 contract additions: registries, as_line, typed AgentJob, RunOptions."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from codeverse.contracts import (
+ ENTRY_FILE,
+ LANGUAGE_LABEL,
+ TRACK_INFO,
+ TRACK_LANGUAGES,
+ AgentJob,
+ ApiAgentOptions,
+ Language,
+ RunOptions,
+ Spec,
+ Track,
+ code_file,
+)
+from codeverse.contracts.artifacts import GateFinding, RenderSet, RenderView, Severity
+
+
+# ------------------------------------------------------------------ registries
+def test_track_info_covers_every_track_and_is_frozen():
+ assert set(TRACK_INFO) == set(Track)
+ assert TRACK_INFO[Track.STATIC_OBJECT].rubric == "static_object_v1"
+ assert TRACK_INFO[Track.ARTICULATED_OBJECT].rubric == "articulated_v1"
+ assert TRACK_INFO[Track.SCENE].rubric == "scene_v1"
+ assert TRACK_INFO[Track.GRAPHICS].rubric == "shader_v1"
+ with pytest.raises(ValidationError):
+ TRACK_INFO[Track.SCENE].rubric = "other" # frozen
+
+
+def test_entry_file_and_labels_cover_every_language():
+ assert set(ENTRY_FILE) == set(Language)
+ assert set(LANGUAGE_LABEL) == set(Language)
+ assert all(e.startswith("src/") for e in ENTRY_FILE.values())
+ assert code_file(Language.BLENDER) == "code.py"
+ assert code_file(Language.THREEJS) == "code.js"
+ assert code_file(Language.GLSL_SHADER) == "code.frag"
+
+
+def test_registries_agree_with_legacy_flywheel_tables():
+ """Drift guard while the legacy tables still exist (they adopt these later)."""
+ import codeverse.flywheel.sample as sample
+
+ legacy_entry = getattr(sample, "ENTRY_BY_LANGUAGE", None)
+ if legacy_entry is not None:
+ assert legacy_entry == ENTRY_FILE
+ legacy_code = getattr(sample, "CODE_FILE_BY_LANGUAGE", None)
+ if legacy_code is not None:
+ assert legacy_code == {lang: code_file(lang) for lang in Language}
+ legacy_label = getattr(sample, "TYPE_LABEL", None)
+ if legacy_label is not None:
+ assert legacy_label == {t: TRACK_INFO[t].label for t in Track}
+
+
+def test_language_frame_covers_every_language():
+ from codeverse.conventions import LANGUAGE_FRAME, Frame
+
+ assert set(LANGUAGE_FRAME) == {lang.value for lang in Language}
+ assert LANGUAGE_FRAME["glsl_shader"] is Frame.Y_UP_POS_Z_FRONT
+ assert LANGUAGE_FRAME["opengl_python"] is Frame.Y_UP_POS_Z_FRONT
+
+
+# ------------------------------------------------------------------ as_line
+def _finding(**kw) -> GateFinding:
+ base = dict(gate="contract", severity=Severity.ERROR, target="leg_1", message="leg floats", fix_hint="drop z by 0.02")
+ base.update(kw)
+ return GateFinding(**base)
+
+
+def test_as_line_default_is_message_plus_fix():
+ assert _finding().as_line() == "leg floats FIX: drop z by 0.02"
+ assert _finding(fix_hint="").as_line() == "leg floats"
+
+
+def test_as_line_flag_combinations():
+ f = _finding()
+ assert f.as_line(with_gate=True, with_hint=False) == "GATE contract: leg floats"
+ assert f.as_line(with_severity=True, with_hint=False) == "[error] leg floats"
+ assert f.as_line(with_target=True, with_hint=False) == "leg floats [leg_1]"
+ assert (f.as_line(with_gate=True, with_severity=True, with_target=True)
+ == "GATE contract: [error] leg floats [leg_1] FIX: drop z by 0.02")
+ assert not f.as_line().startswith("- ")
+
+
+def test_as_line_skips_empty_target():
+ assert _finding(target=None).as_line(with_target=True, with_hint=False) == "leg floats"
+
+
+# ------------------------------------------------------------------ render flags
+def test_render_view_judge_flag_defaults_none():
+ v = RenderView(name="front", path="front.png")
+ assert v.judge is None
+ assert RenderView(name="front", path="front.png", judge=True).judge is True
+ assert RenderSet().out_dir == ""
+
+
+# ------------------------------------------------------------------ AgentJob
+def test_agent_job_legacy_extra_is_lifted_and_kept():
+ extra = {"round": 2, "kind": "refine", "language": "blender", "track": "static_object",
+ "files_hint": ["src/a.py"], "mcp_command": ["python", "-m", "x"],
+ "max_usd": 1.5, "temperature": 0.7, "thinking": "high", "allow_shell": False}
+ j = AgentJob(workspace="w", prompt="p", extra=dict(extra))
+ assert (j.round, j.kind, j.language, j.track) == (2, "refine", "blender", "static_object")
+ assert j.files_hint == ["src/a.py"]
+ assert j.mcp_command == ["python", "-m", "x"]
+ assert j.api == ApiAgentOptions(max_usd=1.5, temperature=0.7, thinking="high", allow_shell=False)
+ assert j.extra == extra # untouched: legacy readers see what they were given
+
+
+def test_agent_job_explicit_fields_beat_extra():
+ j = AgentJob(workspace="w", prompt="p", round=5, api=ApiAgentOptions(max_usd=9.0),
+ extra={"round": 2, "max_usd": 1.0})
+ assert j.round == 5
+ assert j.api.max_usd == 9.0
+
+
+def test_agent_job_defaults_and_roundtrip():
+ j = AgentJob(workspace="w", prompt="p")
+ assert j.round == 0 and j.kind == "" and j.files_hint == [] and j.mcp_command is None
+ assert j.api == ApiAgentOptions()
+ j2 = AgentJob(workspace="w", prompt="p", extra={"round": 3, "temperature": 0.9})
+ assert AgentJob(**j2.model_dump()) == j2 # dump/construct stable
+
+
+# ------------------------------------------------------------------ RunOptions
+def test_spec_options_default_and_legacy_json():
+ s = Spec(id="x", track=Track.STATIC_OBJECT, language=Language.BLENDER, prompt="a chair")
+ assert s.options == RunOptions()
+ d = s.model_dump(mode="json")
+ d.pop("options")
+ s2 = Spec(**d) # old spec.json without options still parses
+ assert s2.options.candidates is None and s2.options.texture is False
+
+
+def test_spec_options_roundtrip_and_validation():
+ s = Spec(id="x", track=Track.SCENE, language=Language.SCENE_THREEJS, prompt="p",
+ options=RunOptions(candidates=3, texture=True))
+ s2 = Spec(**s.model_dump(mode="json"))
+ assert s2.options == RunOptions(candidates=3, texture=True)
+ with pytest.raises(ValidationError):
+ RunOptions(candidates=0) # ge=1
+
+
+def test_spec_options_do_not_change_the_plan_stage_hash():
+ from codeverse.orchestrator.runner import hash_inputs
+ from codeverse.tracks.lifecycle import plan_stage_inputs
+
+ plain = Spec(id="x", track=Track.STATIC_OBJECT, language=Language.BLENDER, prompt="a chair")
+ opted = plain.model_copy(update={"options": RunOptions(candidates=4, texture=True)})
+ assert hash_inputs(plan_stage_inputs(plain)) == hash_inputs(plan_stage_inputs(opted))
+
+
+def test_track_languages_still_the_gate():
+ assert set(TRACK_LANGUAGES) == set(Track)
+ with pytest.raises(ValidationError):
+ Spec(id="x", track=Track.SCENE, language=Language.BLENDER, prompt="p")
diff --git a/harness/tests/core/test_proc.py b/harness/tests/core/test_proc.py
new file mode 100644
index 00000000..84da0596
--- /dev/null
+++ b/harness/tests/core/test_proc.py
@@ -0,0 +1,89 @@
+"""codeverse/proc.py — subprocess primitives (Batch-1 foundations)."""
+
+from __future__ import annotations
+
+import json
+import os
+import resource
+import time
+from pathlib import Path
+
+from codeverse.proc import ProcResult, kill_group, run_subprocess, tail, write_json_atomic
+
+
+def test_run_subprocess_captures_output(tmp_path: Path):
+ r = run_subprocess(["bash", "-c", "echo out; echo err >&2; exit 3"], cwd=tmp_path, timeout_s=10)
+ assert isinstance(r, ProcResult)
+ assert r.returncode == 3
+ assert r.stdout.strip() == "out"
+ assert r.stderr.strip() == "err"
+ assert not r.timed_out
+ assert r.duration_ms >= 0
+
+
+def test_run_subprocess_stdin(tmp_path: Path):
+ r = run_subprocess(["cat"], cwd=tmp_path, timeout_s=10, stdin_text="hello")
+ assert r.stdout == "hello"
+
+
+def test_timeout_kills_the_whole_process_group(tmp_path: Path):
+ """A timed-out child AND its grandchildren die (killpg on the new session)."""
+ r = run_subprocess(["bash", "-c", "sleep 30 & echo $!; wait"], cwd=tmp_path, timeout_s=0.4)
+ assert r.timed_out
+ assert r.returncode != 0
+ grandchild = int(r.stdout.strip().splitlines()[0])
+ deadline = time.monotonic() + 3.0
+ while time.monotonic() < deadline:
+ try:
+ os.kill(grandchild, 0)
+ except ProcessLookupError:
+ return # gone — group kill worked
+ time.sleep(0.05)
+ raise AssertionError(f"grandchild sleep (pid {grandchild}) survived the group kill")
+
+
+def test_preexec_fn_runs_in_the_child(tmp_path: Path):
+ soft = 256
+
+ def limit() -> None:
+ resource.setrlimit(resource.RLIMIT_NOFILE, (soft, soft))
+
+ r = run_subprocess(
+ ["python3", "-c", "import resource, sys; sys.stdout.write(str(resource.getrlimit(resource.RLIMIT_NOFILE)[0]))"],
+ cwd=tmp_path, timeout_s=20, preexec_fn=limit,
+ )
+ assert r.stdout.strip() == str(soft)
+
+
+def test_kill_group_is_public_and_tolerates_dead_proc(tmp_path: Path):
+ import subprocess
+
+ proc = subprocess.Popen(["sleep", "0.05"], start_new_session=True)
+ proc.wait()
+ kill_group(proc) # must not raise on an already-reaped child
+
+
+def test_tail_caps_lines_and_chars():
+ text = "\n".join(f"line{i}" for i in range(100))
+ t = tail(text, max_lines=5)
+ assert t.splitlines() == [f"line{i}" for i in range(95, 100)]
+ assert len(tail("x" * 10000, max_chars=100)) == 100
+
+
+def test_write_json_atomic_no_partial_file(tmp_path: Path):
+ p = tmp_path / "deep" / "out.json"
+ write_json_atomic(p, {"a": 1, "p": Path("b")})
+ assert json.loads(p.read_text()) == {"a": 1, "p": "b"}
+ assert not p.with_suffix(".json.tmp").exists()
+
+
+def test_workspace_write_json_delegates(tmp_ws):
+ from pydantic import BaseModel
+
+ class M(BaseModel):
+ x: int = 2
+
+ p = tmp_ws.root / "artifacts" / "m.json"
+ tmp_ws.write_json(p, M())
+ assert json.loads(p.read_text()) == {"x": 2}
+ assert not p.with_suffix(".json.tmp").exists()