Official Codebase of 3DCodeVerse
Python
tracks/scene: scene.js is only ever assembled — compose-agent fallback, scene_compose.j2 and ServiceUnavailable deleted; the zone stage runs its one session without a fan-out of one
gaoypeng17df56ca1db3
diff --git a/harness/codeverse3d/prompts/tracks/scene_compose.j2 b/harness/codeverse3d/prompts/tracks/scene_compose.j2deleted file mode 100644index b7ba488c..00000000--- a/harness/codeverse3d/prompts/tracks/scene_compose.j2+++ /dev/null@@ -1,53 +0,0 @@-# Compose `{{ title }}` — write `src/scene.js`--The environment (`src/env.js`), zones (`src/zones/*.js`) and assets (`src/assets/*.js`,-`public/assets/*.glb`) exist. Write the entry module that wires them together.-(The harness normally generates this file itself; you are writing the fallback, so match the-generated shape exactly.)--## Contract-{{ frame_doc }}-{{ contract }}-`src/scene.js` must `export async function createScene({ THREE, renderer, loaders }) → { scene, cameras, update }`:-- `scene`: a `THREE.Scene`; build `ctx = { THREE, scene, renderer, loaders, heightAt, assets: {} }`,- call `const env = (await buildEnv(ctx)) || {}` from `./env.js` (ONE argument: ctx), set- `ctx.env = env`, then add every zone group — `build(ctx)` imported from `./zones/<snake>.js`- (the export is named `build`, one argument) — naming each group after its zone.-- `cameras`: an array of PLAIN OBJECTS `{ name, position: [x,y,z], lookAt: [x,y,z], fov }` (the- harness builds the PerspectiveCameras). Use the planned numbers literally. `cameras[0]` is the- establishing shot: it looks at the SUBJECT point, not at the bounds centre, and its height is- above anything standing between it and the subject.-- `update(t, dt)`: calls `env.update(t, dt)` and every zone group's `userData.update(t, dt)`- (collect the list once at creation; never traverse per frame). `tickEnv` and `userData.tick`- are not part of the contract — do not call them.-- Wrap each zone build in try/catch: a failing zone logs `console.error('[zone <name>] ' + err)` and is skipped.-- Use a seeded mulberry32 `rand` (seed 1) so frames are reproducible.-- GLB assets load via `loaders.gltf.loadAsync('/assets/<snake>.glb')` into `ctx.assets` before the- zones build.--## Plan-Bounds: {{ bounds }}-Zones:-{{ zones_table }}-Cameras (author EXACTLY these):-{{ cameras }}-Assets:-{{ asset_api }}-Animation: {{ animation }}--## DON'T-- No DOM, no window/document, no fetch, no CDN imports, no Math.random.-- Do not rebuild env/zones/assets here; only import and place them.-{% if tool_cards and not single_shot %}--## Tools-{{ tool_cards }}-{% endif %}--{% if effects_catalog is defined and effects_catalog %}--{{ effects_catalog }}-{% endif %}--## Output-{{ output_format }}diff --git a/harness/codeverse3d/tracks/common.py b/harness/codeverse3d/tracks/common.pyindex b7a84eaa..2ecb2646 100644--- a/harness/codeverse3d/tracks/common.py+++ b/harness/codeverse3d/tracks/common.py@@ -6,8 +6,7 @@ method here so a test can subclass it with fakes (``tests/orchestrator_tracks/fakes.py``) and an articulated test double can synthesise joint sweeps from theplan. The targets are modules of this same package — never optional — and areimported lazily only to keep ``tracks`` importable without loading Blender,-Chrome or a model client. ``ServiceUnavailable`` is what a FAKE raises for a-service the test did not provide. Nothing here touches a network.+Chrome or a model client. Nothing here touches a network."""from __future__ import annotations@@ -42,11 +41,6 @@ from codeverse3d.workspace import Workspacelog = logging.getLogger(__name__)-class ServiceUnavailable(RuntimeError):- """A test double has no implementation for this service (``scene._assemble_stage``- falls back to an agent compose session on it)."""--def _import(path: str, name: str) -> Any:return getattr(importlib.import_module(path), name)diff --git a/harness/codeverse3d/tracks/scene.py b/harness/codeverse3d/tracks/scene.pyindex 213429eb..87f42274 100644--- a/harness/codeverse3d/tracks/scene.py+++ b/harness/codeverse3d/tracks/scene.py@@ -47,8 +47,8 @@ from codeverse3d.spatial.frame_motion import motion_text_forfrom codeverse3d.spatial.render_scene import perf_detailfrom codeverse3d.texturing.plan import texture_pack_promptfrom codeverse3d.tracks import skills_hook-from codeverse3d.tracks.common import RunContext, ServiceUnavailable, generate_for, single_shot_ctx-from codeverse3d.tracks.generation import GenerationResult, GenerationTask+from codeverse3d.tracks.common import RunContext, generate_for, single_shot_ctx+from codeverse3d.tracks.generation import GenerationTaskfrom codeverse3d.tracks.lifecycle import BaseTrackfrom codeverse3d.tracks.prompting import (SCENE_FILES,@@ -348,38 +348,28 @@ class SceneTrack(BaseTrack):plan: ScenePlan = ctx.plan # type: ignore[assignment]t0 = time.time()# one author for the whole world (D70; the fan-out control arm was removed 2026-09-21)- batches = [list(plan.zones)]- if any(len(b) > 1 for b in batches):- ctx.events.emit("zones.batched", batches=[[z.name for z in b] for b in batches])-- # once, before the fan-out: every zone session shares one workspace, so three- # parallel attaches would race the same AGENTS.md. The zone rows (R3 "zone",- # R14/R18 "zone") are identical for every batch, so one route is the right route.+ zones = list(plan.zones)+ if len(zones) > 1:+ ctx.events.emit("zones.batched", batches=[[z.name for z in zones]])zone_gen = self._strategy(ctx, "zones")skills_hook.attach_for_round(zone_gen, index=0, kind="zone")-- def _one(batch: list[ZonePlan]) -> GenerationResult:- task = skills_hook.with_inlined_skill(zone_gen, [self._zone_task(zone_gen, batch)])[0]- return generate_for(zone_gen, task)-- results = fan_out(batches, _one, max_workers=ctx.settings.limits.max_parallel_agents, label="zones",- item_name=lambda b: "+".join(z.name for z in b))out: dict[str, Any] = {}- for batch, r in zip(batches, results, strict=True):- if isinstance(r, Exception):- # BudgetExceeded included: the sibling zones' paid modules are still- # recorded + committed; the guard's boundary check below stops the run.- for zone in batch:- out[zone.name] = {"ok": False, "notes": f"{type(r).__name__}: {r}"}- else:- written = {c.path for c in r.files_changed}- for zone in batch:- rel = zone_file(zone)- # a batched session must have produced EVERY file it owns; the skeleton- # left a stub at every zone path, so existence proves nothing — the file- # must have been reported as changed or actually rewritten in this stage- ok = r.ok and (len(batch) == 1 or rel in written or _touched(ctx.ws.root / rel, t0))- out[zone.name] = {"ok": ok, "files": [rel] if ok else [], "notes": r.notes}+ try:+ task = skills_hook.with_inlined_skill(zone_gen, [self._zone_task(zone_gen, zones)])[0]+ r = generate_for(zone_gen, task)+ except Exception as e: # noqa: BLE001 — BudgetExceeded included: the stage is still+ # recorded + committed; the guard's boundary check below stops the run+ log.warning("zones session failed: %s: %s", type(e).__name__, e)+ out = {zone.name: {"ok": False, "notes": f"{type(e).__name__}: {e}"} for zone in zones}+ else:+ written = {c.path for c in r.files_changed}+ for zone in zones:+ rel = zone_file(zone)+ # a session that owns several zones must have produced EVERY file; the skeleton+ # left a stub at every zone path, so existence proves nothing — the file+ # must have been reported as changed or actually rewritten in this stage+ ok = r.ok and (len(zones) == 1 or rel in written or _touched(ctx.ws.root / rel, t0))+ out[zone.name] = {"ok": ok, "files": [rel] if ok else [], "notes": r.notes}self._record_skills(zone_gen, "zone")ctx.ws.commit("zones")ctx.events.emit("zones.done", ok=[k for k, v in out.items() if v["ok"]], failed=[k for k, v in out.items() if not v["ok"]])@@ -428,22 +418,10 @@ class SceneTrack(BaseTrack):timeout_s=ctx.budget.timeout_s(ZONE_TIMEOUT_S * max(1, len(batch)), floor_s=180))def _assemble_stage(self, ctx: RunContext) -> dict[str, Any]:- try:- result = ctx.services.assemble_scene(ctx.ws, ctx.plan)- ctx.ws.commit("assemble")- ctx.events.emit("assemble.done", deterministic=True)- return {"ok": True, "deterministic": True, "result": result} # StageRunner.stage jsonables it- except ServiceUnavailable as e:- ctx.events.emit("assemble.fallback", reason=str(e))- prompt = render("tracks/scene_compose.j2", **self._ctx(ctx))- ctx.record_prompt("scene_compose", prompt)- task = GenerationTask(label="compose", prompt=prompt, system=self.system_prompt(ctx), files_hint=["src/scene.js"], round=0,- kind="compose", temperature=0.4, owns_entry=True, images=reference_images(ctx))- task = self._deliver_skills(ctx, "compose", [task])[0]- res = generate_for(ctx, task)- self._record_skills(ctx, "compose")- ctx.ws.commit("compose")- return {"ok": res.ok, "deterministic": False, "files": [c.path for c in res.files_changed], "notes": res.notes}+ result = ctx.services.assemble_scene(ctx.ws, ctx.plan)+ ctx.ws.commit("assemble")+ ctx.events.emit("assemble.done", deterministic=True)+ return {"ok": True, "deterministic": True, "result": result} # StageRunner.stage jsonables itdef prepare_salvage(self, ctx: RunContext) -> bool:"""The budget stopped a stage before round 0: assemble whatever the stages DIDdiff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 5b612f38..25703f58 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -476,7 +476,7 @@ GenerationTask.phase: int = 0 # tasks run in parallel WITHIN a phase, phases igenerate(ws, *, agent_id, task, ..., budget=BudgetGuard, max_turns=0, wrapup_turns=6) -> GenerationResult# GenerationResult.storm: every session died on a transient streak (AgentResult.transient) and wrote nothingtracks.common.generate_for(ctx: RunContext, task: GenerationTask) -> GenerationResult- # THE call every stage makes (env, zones, compose, rounds, repairs, asset ladder, judged fix): generate()+ # THE call every stage makes (env, zones, rounds, repairs, asset ladder, judged fix): generate()# with everything ctx knows, and a storm-dead task retried through single_shot_ctx(ctx) (D68)tracks.common.single_shot_agent_id(agent_id, chat_model_id='') -> str · single_shot_ctx(ctx) -> RunContext | None# moved from tracks.scene_assets 2026-09-07 (never scene-specific)diff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.mdindex 203bd8ba..1a9e6b76 100644--- a/harness/docs/SKILLS.md+++ b/harness/docs/SKILLS.md@@ -538,9 +538,10 @@ so; the rest are live.generated the whole baseline (`_env_stage`, `_zones_stage`, `_assemble_stage`) without everreaching `skills_hook.attach_for_round`, which lived only in `steps.run_round`; and`baseline_tasks` returned `[]`, so round 0 listed four bundles to a session that did not- exist. Measured at **0 opens / 30 listings**. The three stages now attach and record with- their own kind. `tests/skills/test_delivery_reaches_the_session.py` runs a real- two-zone-session scene and proves env/zone/compose attach exactly once, before generation,+ exist. Measured at **0 opens / 30 listings**. The generating stages now attach and record with+ their own kind (`scene.js` is assembled without a session since the compose fallback went,+ 2026-09-22). `tests/skills/test_delivery_reaches_the_session.py` runs a real+ two-zone-session scene and proves env/zone attach exactly once, before generation,with matching telemetry. **The scene bundles' read rate against working deliveryis UNMEASURED — that is the next wave's first experiment.*** ~~**`api-agent` has no skill affordance.**~~ **FIXED earlier**, and re-measured here: withdiff --git a/harness/tests/orchestrator_tracks/fakes.py b/harness/tests/orchestrator_tracks/fakes.pyindex c12dd290..d04607c5 100644--- a/harness/tests/orchestrator_tracks/fakes.py+++ b/harness/tests/orchestrator_tracks/fakes.py@@ -31,12 +31,16 @@ from codeverse3d.contracts.common import Language, Usagefrom codeverse3d.contracts.plan import Planfrom codeverse3d.contracts.run import RunRecordfrom codeverse3d.conventions import to_snake-from codeverse3d.tracks.common import Services, ServiceUnavailable+from codeverse3d.tracks.common import Servicesfrom codeverse3d.workspace import WorkspaceFAIL_MARK = "RAISE_BUILD_ERROR"+class ServiceUnavailable(RuntimeError):+ """This fake has no implementation for the service (the test did not provide one)."""++# ----------------------------------------------------------------------------- runtimeclass FakeRuntime:"""Writes a tiny GLB (one box per part) on build; fails when a src file contains FAIL_MARK."""@@ -257,7 +261,7 @@ def _png(path: Path, size: int = 32) -> None:class FakeServices(Services):def __init__(self, *, runtime_factory: Callable[[Language], Any] | None = None, judge: Any | None = None,- contract_errors: int = 0, assemble: bool = False, sweep_errors: int = 0, pairwise: Any | None = None,+ contract_errors: int = 0, assemble: bool = True, sweep_errors: int = 0, pairwise: Any | None = None,silhouette_iou: float | None = None, motion_errors: int = 0):self.runtime_factory = runtime_factory or (lambda lang: FakeRuntime(lang))self._judge = judgediff --git a/harness/tests/orchestrator_tracks/test_prompts_assets.py b/harness/tests/orchestrator_tracks/test_prompts_assets.pyindex 7f8df13c..38ef9355 100644--- a/harness/tests/orchestrator_tracks/test_prompts_assets.py+++ b/harness/tests/orchestrator_tracks/test_prompts_assets.py@@ -22,7 +22,7 @@ from tests.orchestrator_tracks.fakes import FakeAgent, FakeJudge, FakeRuntime, FTEMPLATES = {"plan_static", "plan_articulated", "plan_scene", "generate_static", "generate_articulated", "refine_object", "repair","generate_static_part", "assemble_static", "detail_object",- "scene_asset", "scene_env", "scene_zone", "scene_compose", "scene_refine"}+ "scene_asset", "scene_env", "scene_zone", "scene_refine"}def _asset_module(job) -> str:@@ -117,7 +117,7 @@ def test_scene_templates_render_and_asset_stage_with_blender(tmp_ws, settings):from codeverse3d.tracks.scene import SceneTrackst = SceneTrack(services=services)- for tpl, extra in (("scene_env", {}), ("scene_compose", {}),+ for tpl, extra in (("scene_env", {}),("scene_zone", dict(zone_name="Quay", zone_description="d", zone_bbox="b", zone_contents=["Bollard"], zone_file="src/zones/quay.js", neighbours=["Water: x"])),("scene_refine", dict(round_index=1, tasks=["t"], targets=["Quay"], files=["src/zones/quay.js"], edit_only_these=False, judge_summary="j", current_files={}))):out = render(f"tracks/{tpl}.j2", **st._ctx(ctx, **extra))diff --git a/harness/tests/orchestrator_tracks/test_tracks.py b/harness/tests/orchestrator_tracks/test_tracks.pyindex 9cfb3a93..61529e69 100644--- a/harness/tests/orchestrator_tracks/test_tracks.py+++ b/harness/tests/orchestrator_tracks/test_tracks.py@@ -187,8 +187,6 @@ def _scene_writer(job, ws):return {rel: f"export function build(){{}} // {label}\n" for rel in job.files_hint}if label.startswith("zone_"):return {f"src/zones/{label[5:]}.js": f"export function build(){{}} // {label}\n"}- if label == "compose":- return {"src/scene.js": "export function createScene(){}\n"}if label.startswith("refine"):return {f: f"// refined by {label}\n" for f in job.prompt.split("EDIT ONLY THESE FILES")[-1].splitlines() if False} or {"src/scene.js": f"// {label}\n"}return {"src/scene.js": "// x\n"}@@ -202,7 +200,7 @@ def test_scene_track_stages_and_rounds(tmp_path, settings):spec = make_spec(Track.SCENE, Language.SCENE_THREEJS, max_rounds=1, prompt="a small harbour at dusk")ws = Workspace(tmp_path / "runs" / "harbour")agent = FakeAgent(_scene_writer)- services = FakeServices(assemble=False)+ services = FakeServices()track = SceneTrack(services=services, judge=FakeJudge(scores=(0.6, 0.7), targets=("Quay", "Water")), agent=agent,planner_model=_planner(plan.model_dump(mode="json")), settings=settings, runtime=FakeRuntime(Language.SCENE_THREEJS))rec = track.run(spec, ws)@@ -210,8 +208,7 @@ def test_scene_track_stages_and_rounds(tmp_path, settings):# Quay and Water are both small zones (≤ 3 placements) → ONE batched session owning both files# assets ∥ env: the combined stage's three sessions interleave freely; order resumes at zonesassert set(labels[:3]) == {"asset_fishing_boat", "asset_bollard", "env"} and "zones_quay_water" in labels- assert "compose" in labels # assembler unavailable → composer agent fallback- assert labels.index("env") < labels.index("zones_quay_water") < labels.index("compose")+ assert "compose" not in labels and labels.index("env") < labels.index("zones_quay_water") # scene.js is assembledassert (ws.src / "assets" / "fishing_boat.js").is_file() and (ws.src / "zones" / "quay.js").is_file() and (ws.src / "scene.js").is_file()zone_prompt = next(j.prompt for j in agent.jobs if j.label == "zones_quay_water")assert "buildFishingBoat" in zone_prompt and "8.00×3.50×3.00" in zone_prompt and "Neighbouring zones" in zone_promptdiff --git a/harness/tests/scene_runtime/test_skeleton.py b/harness/tests/scene_runtime/test_skeleton.pyindex 1b68e8b6..767abd48 100644--- a/harness/tests/scene_runtime/test_skeleton.py+++ b/harness/tests/scene_runtime/test_skeleton.py@@ -139,7 +139,7 @@ def test_the_effects_catalog_reaches_the_scene_prompts_and_only_those():assert effects_catalog_text(Language.GLSL_SHADER) == ""tpl = PROMPTS_DIR / "tracks"- for name in ("scene_env.j2", "scene_zone.j2", "scene_refine.j2", "scene_compose.j2"):+ for name in ("scene_env.j2", "scene_zone.j2", "scene_refine.j2"):assert "effects_catalog" in (tpl / name).read_text(), name# the asset session authors BLENDER bpy, so it must NOT carry the tableassert "effects_catalog" not in (tpl / "scene_asset.j2").read_text()diff --git a/harness/tests/skills/test_delivery_reaches_the_session.py b/harness/tests/skills/test_delivery_reaches_the_session.pyindex 034db05b..66933613 100644--- a/harness/tests/skills/test_delivery_reaches_the_session.py+++ b/harness/tests/skills/test_delivery_reaches_the_session.py@@ -2,14 +2,14 @@The read loop measured c3d-scene-composition / -lighting / -motion at 0 opens out of 3listings each and read it as a wording problem. It was not: the scene track did all of-its baseline generation in ``prepare()`` — the env, zones and compose stages called+its baseline generation in ``prepare()`` — the env and zones stages called``tracks.generation.generate`` directly — while ``skills_hook.attach_for_round`` was onlyreached from ``steps.run_round``. ``SceneTrack.baseline_tasks`` returns ``[]``, so round 0listed the bundles to a round that had no generation task to consume them. That wasexactly "listed 3, opened 0", and no rewrite of a SKILL.md could have fixed it.-CLOSED 2026-08-25 (curate wave): ``SceneTrack._env_stage`` / ``_zones_stage`` /-``_assemble_stage`` now go through ``_deliver_skills`` + ``_record_skills``. These tests+CLOSED 2026-08-25 (curate wave): ``SceneTrack._env_stage`` / ``_zones_stage`` now go+through the skill hook + ``_record_skills`` (``scene.js`` is assembled, no session). These testskeep every agent-driving module on the hook, so the gap cannot reopen quietly. The scenebundles' read rate is UNMEASURED against this delivery — that is the next wave's firstexperiment, and until it runs their ledger rows stay ``mixed``/``inherited``, not@@ -46,7 +46,7 @@ def scene_run(tmp_path, monkeypatch):prompt="a small harbour at dusk")ws = Workspace(tmp_path / "runs" / "harbour_skills")agent = FakeAgent(_scene_writer)- track = SceneTrack(services=FakeServices(assemble=False), judge=FakeJudge(scores=(0.6,)),+ track = SceneTrack(services=FakeServices(), judge=FakeJudge(scores=(0.6,)),agent=agent, planner_model=_planner(plan.model_dump(mode="json")),settings=Settings(), runtime=FakeRuntime(Language.SCENE_THREEJS))rec = track.run(spec, ws)@@ -58,17 +58,14 @@ def test_every_scene_generation_stage_gets_skills_before_its_sessions(scene_run)rec, agent, ws = scene_runevents = EventLog(ws.events_path).read()attachments = [e for e in events if e.get("event") == "skills.attached"]- by_kind = {e["kind"]: e for e in attachments if e.get("kind") in {"env", "zone", "compose"}}+ by_kind = {e["kind"]: e for e in attachments if e.get("kind") in {"env", "zone"}}- assert Counter(e.get("kind") for e in attachments) >= Counter(- {"env": 1, "zone": 1, "compose": 1}- )+ assert Counter(e.get("kind") for e in attachments) >= Counter({"env": 1, "zone": 1})assert all(sum(e.get("kind") == kind for e in attachments) == 1 for kind in by_kind)assert {"c3d-scene-composition", "c3d-scene-lighting"} <= set(by_kind["env"]["skills"])assert {"c3d-scene-composition", "c3d-scene-motion", "c3d-bbox-contract"} <= set(by_kind["zone"]["skills"])- assert {"c3d-scene-composition", "c3d-scene-motion"} <= set(by_kind["compose"]["skills"])def belongs(kind: str, event: dict) -> bool:label = str(event.get("label", ""))@@ -81,7 +78,7 @@ def test_every_scene_generation_stage_gets_skills_before_its_sessions(scene_run)generated_at = [i for i, event in enumerate(events) if belongs(kind, event)]assert generated_at and all(attach_at < i for i in generated_at), kindassert sum(belongs("zone", event) for event in events) == 1 # D70: one session owns every zone file- assert Counter(job.kind for job in agent.jobs) >= Counter({"env": 1, "zone": 1, "compose": 1})+ assert Counter(job.kind for job in agent.jobs) >= Counter({"env": 1, "zone": 1})telemetry_path = ws.root / "telemetry" / "skills.jsonl"assert telemetry_path.is_file()