Official Codebase of 3DCodeVerse
Python
scene: the env, zone and compose sessions were never offered their skills
gaoypeng50dd4fd74ce6
diff --git a/harness/codeverse/tracks/scene.py b/harness/codeverse/tracks/scene.pyindex b51e0653..f5bd88ad 100644--- a/harness/codeverse/tracks/scene.py+++ b/harness/codeverse/tracks/scene.py@@ -44,6 +44,7 @@ from codeverse.orchestrator.runner import StageRunnerfrom codeverse.prompts import renderfrom codeverse.spatial.frame_motion import motion_text_forfrom codeverse.spatial.render_scene import JUDGE_MAX_VIEWS, perf_detail+from codeverse.tracks import skills_hookfrom codeverse.tracks.common import RunContext, ServiceUnavailablefrom codeverse.tracks.generation import GenerationResult, GenerationTask, generatefrom codeverse.tracks.lifecycle import BaseTrack@@ -212,14 +213,48 @@ class SceneTrack(BaseTrack):ctx.events.emit("budget.degraded", note=note, spent_usd=round(ctx.budget.spent.cost_usd, 4),elapsed_min=round(ctx.budget.elapsed_minutes(), 2))+ # ---- skills -----------------------------------------------------------+ def _deliver_skills(self, gen: RunContext, stage_kind: str,+ tasks: Sequence[GenerationTask]) -> list[GenerationTask]:+ """Route this stage's bundles into the workspace and inline them if single-shot.++ WHY this is not just ``steps.run_round``'s job. A scene builds its whole baseline+ in ``prepare()``: ``_env_stage`` writes the lighting, ``_zones_stage`` the contents,+ ``_assemble_stage`` the cameras — three real agent sessions that never passed+ through ``steps.run_round``, the ONE place that called ``attach_for_round``. The+ router has always had ``kinds=("env", "zone", "compose")`` rows for the four scene+ bundles (registry R14-R21), so they were selected for these very stages and then+ delivered to nobody: measured 2026-08-25 at 0 opens out of 30 listings, while round+ 0's ``baseline_tasks`` returned ``[]`` and so listed them to a session that did not+ exist. That is the whole of the scene bundles' "unread", and no wording could+ have fixed it.++ ``index=0`` because these stages ARE round 0's generation; there is no earlier+ round, so ``_previous_findings`` correctly returns nothing and only the plan-signal+ and kind rows can fire. Attaching once per stage (not once per task) keeps the+ parallel zone sessions from racing each other's AGENTS.md write.+ """+ skills_hook.attach_for_round(gen, index=0, kind=stage_kind)+ return skills_hook.with_inlined_skill(gen, tasks)++ def _record_skills(self, gen: RunContext, stage_kind: str) -> None:+ """Close the stage's telemetry row so the denominator counts sessions, not stages.++ Without this a scene run reports ``skills.attached`` three times and ``skills.read``+ never, which reads in ``3dcv skills report`` as "listed, unread" — the same false+ signal the delivery gap itself produced."""+ skills_hook.record_usage(gen, index=0, kind=stage_kind)+def _env_stage(self, ctx: RunContext) -> dict[str, Any]:gen = self._strategy(ctx, "env")prompt = render("tracks/scene_env.j2", **self._ctx(gen, recipes=cookbook_sections(gen, ENV_RECIPES)))ctx.record_prompt("scene_env", prompt)task = GenerationTask(label="env", prompt=prompt, system=self.system_prompt(ctx), files_hint=["src/env.js"], round=0, kind="env",temperature=0.5, timeout_s=ctx.budget.timeout_s(ENV_TIMEOUT_S, floor_s=120))+ task = self._deliver_skills(gen, "env", [task])[0]res = generate(ctx.ws, agent_id=gen.agent_id, task=task, agent=gen.agent, model=gen.model, settings=ctx.settings,budget=ctx.budget, events=ctx.events)+ self._record_skills(gen, "env")ctx.ws.commit("env")return {"ok": res.ok, "files": [c.path for c in res.files_changed], "notes": res.notes}@@ -230,9 +265,15 @@ class SceneTrack(BaseTrack):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.+ zone_gen = self._strategy(ctx, "zones")+ skills_hook.attach_for_round(zone_gen, index=0, kind="zone")+def _one(batch: list[ZonePlan]) -> GenerationResult:gen = self._strategy(ctx, "zones")- task = self._zone_task(gen, batch)+ task = skills_hook.with_inlined_skill(gen, [self._zone_task(gen, batch)])[0]return generate(ctx.ws, agent_id=gen.agent_id, task=task, agent=gen.agent, model=gen.model, settings=ctx.settings,budget=ctx.budget, events=ctx.events)@@ -256,6 +297,7 @@ class SceneTrack(BaseTrack):# must have been reported as changed or actually rewritten in this stageok = 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}+ 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"]])return out@@ -302,8 +344,10 @@ class SceneTrack(BaseTrack):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)+ task = self._deliver_skills(ctx, "compose", [task])[0]res = generate(ctx.ws, agent_id=ctx.agent_id, task=task, agent=ctx.agent, model=ctx.model, settings=ctx.settings,budget=ctx.budget, events=ctx.events)+ 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}diff --git a/harness/tests/skills/test_delivery_reaches_the_session.py b/harness/tests/skills/test_delivery_reaches_the_session.pyindex e83e082f..0e2ffbab 100644--- a/harness/tests/skills/test_delivery_reaches_the_session.py+++ b/harness/tests/skills/test_delivery_reaches_the_session.py@@ -1,25 +1,34 @@"""A routed bundle only exists if a GENERATING session is told about it.The read loop measured cv3d-scene-composition / -lighting / -motion at 0 opens out of 3-listings each and read it as a wording problem. It is not: the scene track does all of-its baseline generation in ``prepare()`` — the env, zones and compose stages call-``tracks.generation.generate`` directly — while ``skills_hook.attach_for_round`` is only-reached from ``steps.run_round``. ``SceneTrack.baseline_tasks`` then returns ``[]``, so-round 0 attaches the bundles to a round that has no generation task to consume them.-That is exactly "listed 3, opened 0", and no rewrite of a SKILL.md can change it.--These tests pin the shape of the gap so it cannot widen quietly, and so that the day the-scene stages are routed through the hook the strict xfail turns the suite red and forces-this file, docs/SKILLS_LEDGER.md and the bundles' evidence labels to be revisited together.+listings 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+``tracks.generation.generate`` directly — while ``skills_hook.attach_for_round`` was only+reached from ``steps.run_round``. ``SceneTrack.baseline_tasks`` returns ``[]``, so round 0+listed the bundles to a round that had no generation task to consume them. That was+exactly "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+keep every agent-driving module on the hook, so the gap cannot reopen quietly. The scene+bundles' read rate is UNMEASURED against this delivery — that is the next wave's first+experiment, and until it runs their ledger rows stay ``mixed``/``inherited``, not+``measured``."""from __future__ import annotationsimport ast+import contextlib+import jsonfrom pathlib import Pathimport pytest+from codeverse.contracts.common import Language, Track+from codeverse.contracts.plan import ScenePlan+from codeverse.workspace import Workspace+TRACKS = Path(__file__).resolve().parents[2] / "codeverse" / "tracks"#: modules that hand a GenerationTask to a coding agent, and whether the skills hook is@@ -49,34 +58,150 @@ def test_the_module_really_does_generate(mod: str) -> None:assert _calls_generate(mod), f"{mod} no longer calls generate(task=...)"[email protected]("mod", ["steps.py", "repair.py"])-def test_the_round_and_repair_paths_deliver_skills(mod: str) -> None:[email protected]("mod", ["steps.py", "repair.py", "scene.py"])+def test_every_generating_path_delivers_skills(mod: str) -> None:+ """The whole point. ``scene_assets`` is exempt (see GENERATING_MODULES)."""assert _mentions_hook(mod), f"{mod} drives an agent without going through skills_hook"[email protected](strict=True, reason=(- "KNOWN GAP, measured 2026-08-25: the scene track generates its whole baseline in "- "prepare() (env/zones/compose stages -> generate()), which never reaches "- "skills_hook.attach_for_round. The four scene-routed bundles were listed 3 times each "- "and opened 0 times because of this, and cv3d-scene-composition's target metric is read "- "on the FIRST gated round, which those stages produce. Fix: call attach_for_round + "- "with_inlined_skill in SceneTrack._env_stage / _zone_task / _compose, as steps.run_round "- "does. When this XPASSes, re-measure the scene bundles' read rate and effect."))-def test_the_scene_stages_deliver_skills() -> None:- assert _mentions_hook("scene.py"), (- "scene.py drives three generating sessions and none of them is offered the routed "- "bundles: the scene skills cannot affect a scene baseline as delivered")[email protected]("stage_kind", ["env", "zone", "compose"])+def test_each_scene_stage_attaches_its_own_kind(stage_kind: str) -> None:+ """Not just "the module imports the hook": each of the three stages must attach with+ the kind the router's rows are written against (registry R14-R21 name env/zone/compose).+ Attaching them all as "baseline" would route a different set and quietly re-open the gap."""+ src = (TRACKS / "scene.py").read_text()+ assert f'"{stage_kind}"' in src+ attaches = [n for n in ast.walk(ast.parse(src))+ if isinstance(n, ast.Call) and _kind_arg(n) == stage_kind]+ assert attaches, f"no scene stage delivers skills with kind={stage_kind!r}"+++def _kind_arg(node: ast.Call) -> str | None:+ """The ``kind=``/stage-kind literal of an attach_for_round or _deliver_skills call."""+ name = getattr(node.func, "attr", getattr(node.func, "id", ""))+ if name not in ("attach_for_round", "_deliver_skills", "_record_skills"):+ return None+ for kw in node.keywords:+ if kw.arg == "kind" and isinstance(kw.value, ast.Constant):+ return str(kw.value.value)+ for arg in node.args: # _deliver_skills(gen, "env", [task])+ if isinstance(arg, ast.Constant) and isinstance(arg.value, str):+ return arg.value+ return None+++def test_the_zone_fan_out_attaches_once_not_once_per_batch() -> None:+ """Zone sessions run in parallel against ONE workspace. Attaching inside the worker+ would have three threads writing the same AGENTS.md; the route is identical for every+ batch, so it belongs outside the fan-out."""+ src = (TRACKS / "scene.py").read_text()+ body = src.split("def _zones_stage", 1)[1].split("\n def ", 1)[0]+ worker = body.split("def _one", 1)[1].split("results = fan_out", 1)[0]+ assert "attach_for_round" not in worker, "zone skills are attached inside the fan-out worker"+ assert "attach_for_round" in body.split("def _one", 1)[0], "the zone stage never attaches"def test_round_zero_of_a_scene_run_has_no_generation_task() -> None:- """The other half of the same fact, and the reason the bundles look 'listed'.+ """The other half of the old fact, still true and still worth pinning.- ``attach_for_round`` still fires for round 0, so the round record names the routed- bundles — while ``baseline_tasks`` hands ``run_generation_tasks`` an empty list, so no- session is ever created to read them. A read-rate denominator built from listings- therefore counts sessions that never existed.+ Round 0 attaches and generates nothing, because the generation already happened in the+ stages. That is fine now that the stages deliver — but it means a read-rate+ denominator built from round records alone still counts a session that never existed.+ Count the STAGES' telemetry rows (``_record_skills``), not round 0's listing."""src = (TRACKS / "scene.py").read_text()assert "def baseline_tasks" in srcbody = src.split("def baseline_tasks", 1)[1].split("def ", 1)[0]assert "return []" in body, "scene round 0 now generates; the listing-vs-read gap may be gone"+++# --------------------------------------------------------------------------- runtime proof+# The tests above read the source. This one runs a real scene track (repo fakes: no+# network, no node, no Blender) and asserts the bundles reach the actual env/zone/compose+# SESSIONS -- which is the thing the old gap made false, and the thing a source-level+# assertion cannot prove.+++def scene_run(tmp_path, monkeypatch):+ from codeverse.config import Settings+ from codeverse.tracks.plan_examples import plan_example+ from codeverse.tracks.scene import SceneTrack+ from tests.orchestrator_tracks.conftest import make_spec+ from tests.orchestrator_tracks.fakes import FakeAgent, FakeJudge, FakeRuntime, FakeServices+ from tests.orchestrator_tracks.test_tracks import _planner, _scene_writer++ monkeypatch.setenv("CV3D_SKILLS", "1")+ plan = ScenePlan.model_validate(plan_example(Track.SCENE))+ plan.assets = [a for a in plan.assets if a.kind == "threejs"]+ for z in plan.zones:+ z.contents = [c for c in z.contents if c in {a.name for a in plan.assets}]+ spec = make_spec(Track.SCENE, Language.SCENE_THREEJS, max_rounds=0,+ 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,)),+ agent=agent, planner_model=_planner(plan.model_dump(mode="json")),+ settings=Settings(), runtime=FakeRuntime(Language.SCENE_THREEJS))+ rec = track.run(spec, ws)+ return rec, agent, ws+++def test_the_env_session_is_really_offered_the_scene_bundles(scene_run) -> None:+ """The bug in one assertion.++ Asserting on AGENTS.md *after* the run would pass either way: round 0 still calls+ attach_for_round(kind="baseline") once the stages are done, so the files land in the+ workspace regardless -- which is precisely how this gap hid as "listed 3, opened 0".+ The honest assertion is the ``skills.attached`` event carrying kind="env", emitted+ before the env session ran and by nothing else.+ """+ _, agent, ws = scene_run+ attached = _attached_events(ws)+ env = [e for e in attached if e.get("kind") == "env"]+ assert env, (f"no skills.attached event for the env stage; kinds seen: "+ f"{sorted({e.get('kind') for e in attached})}. The env session -- where a "+ f"scene's lighting is authored -- was never offered its bundles")+ assert "cv3d-scene-lighting" in (env[0].get("skills") or []), (+ f"the env stage attached {env[0].get('skills')}, without cv3d-scene-lighting; "+ "router row R16 selects it for kind='env'")+++def test_the_stage_attach_happens_before_the_stage_generates(scene_run) -> None:+ """Order is the whole point: a bundle written after the session is a bundle nobody saw."""+ _, _, ws = scene_run+ rows = _events(ws)+ def first(pred):+ return next((i for i, e in enumerate(rows) if pred(e)), None)+ att = first(lambda e: e.get("event") == "skills.attached" and e.get("kind") == "env")+ gen = first(lambda e: "env" in str(e.get("label", "")) and "gen" in str(e.get("event", "")))+ assert att is not None+ if gen is not None:+ assert att < gen, "the env stage attached its skills after it had already generated"+++def _events(ws) -> list[dict]:+ p = Path(ws.root) / "events.jsonl"+ if not p.is_file():+ return []+ out: list[dict] = []+ for ln in p.read_text().splitlines():+ if ln.strip():+ with contextlib.suppress(json.JSONDecodeError):+ out.append(json.loads(ln))+ return out+++def _attached_events(ws) -> list[dict]:+ return [e for e in _events(ws) if e.get("event") == "skills.attached"]+++def test_every_scene_stage_leaves_a_telemetry_row(scene_run) -> None:+ """Without a row per stage the denominator counts stages that never reported, which is+ how "listed, unread" was manufactured in the first place."""+ _, _, ws = scene_run+ p = Path(ws.root) / "telemetry" / "skills.jsonl"+ if not p.is_file():+ pytest.skip("skills telemetry is not written by the fakes on this path")+ kinds = {json.loads(ln)["kind"] for ln in p.read_text().splitlines() if ln.strip()}+ assert {"env", "zone"} <= kinds, f"stages missing from telemetry: {kinds}"