Official Codebase of 3DCodeVerse
Python
refine: the write tool holds the scope the prompt only asked for
gaoypengd17003ffc5b1
diff --git a/harness/codeverse/agents/api_agent.py b/harness/codeverse/agents/api_agent.pyindex 8386e62f..d759e86f 100644--- a/harness/codeverse/agents/api_agent.py+++ b/harness/codeverse/agents/api_agent.py@@ -97,10 +97,18 @@ class _Loop:def __init__(self, agent: ApiAgent, s: Session, chat: Any):self.agent, self.s, self.chat = agent, s, chatjob = s.job- self.files = FileTools(s.ws, job.write_roots, allow_shell=job.api.allow_shell)+ self.files = FileTools(+ s.ws,+ job.write_roots,+ allow_shell=job.api.allow_shell,+ edit_only=job.files_hint if job.edit_only else None,+ always_writable=job.always_writable,+ )self.spatial: SpatialTools | None = Noneif job.spatial_tools:- self.spatial = SpatialTools(s.ws, track=job.track, language=job.language, round_index=job.round)+ self.spatial = SpatialTools(+ s.ws, track=job.track, language=job.language, round_index=job.round+ )if not self.spatial.tools:s.notes.append("spatial registry is empty; running with file tools only")self.spatial = None@@ -111,8 +119,11 @@ class _Loop:# a backend WITHOUT a native loader gets the routed set as a tool; the policy lives# in skills/delivery.py so a new backend is one row there, not a branch hereself.skills = SkillTools(s.ws) if delivery_for(agent.kind).needs_tool else None- self.specs: list[ToolSpec] = (self.files.specs() + (self.skills.specs() if self.skills else [])- + (self.spatial.specs() if self.spatial else []))+ self.specs: list[ToolSpec] = (+ self.files.specs()+ + (self.skills.specs() if self.skills else [])+ + (self.spatial.specs() if self.spatial else [])+ )self.usage = Usage(backend="api-agent", model=agent.model)self.tool_calls = 0self.last_write_turn = -1@@ -139,7 +150,10 @@ class _Loop:ok, reason, text = False, "budget", ""for turn in range(job.max_turns):if time.monotonic() > self.t_deadline:- reason, self.errors = "timeout", self.errors + [f"wall clock exceeded {job.timeout_s}s"]+ reason, self.errors = (+ "timeout",+ self.errors + [f"wall clock exceeded {job.timeout_s}s"],+ )breakresp = self._generate(turn)if resp is None:@@ -147,9 +161,16 @@ class _Loop:breaktext = resp.textself.messages.append(_assistant_message(resp))- traj.append("assistant", turn=turn, text=resp.text[:20000],- tool_calls=[{"id": c.id, "name": c.name, "arguments": c.arguments} for c in resp.tool_calls],- usage=resp.usage.model_dump(), finish_reason=resp.finish_reason)+ traj.append(+ "assistant",+ turn=turn,+ text=resp.text[:20000],+ tool_calls=[+ {"id": c.id, "name": c.name, "arguments": c.arguments} for c in resp.tool_calls+ ],+ usage=resp.usage.model_dump(),+ finish_reason=resp.finish_reason,+ )if not resp.tool_calls:if self._needs_build_nudge():self.nudged = True@@ -160,21 +181,38 @@ class _Loop:breakself._execute(turn, resp.tool_calls)if self.max_usd and self.usage.cost_usd > self.max_usd:- reason, self.errors = "budget", self.errors + [f"cost {self.usage.cost_usd:.3f} > max_usd {self.max_usd}"]+ reason, self.errors = (+ "budget",+ self.errors + [f"cost {self.usage.cost_usd:.3f} > max_usd {self.max_usd}"],+ )breakif message_chars(self.messages) > COMPACT_AT_CHARS:self.messages = compact_messages(self.messages, keep_recent=6, facts=self._facts())traj.append("compact", turn=turn, chars=message_chars(self.messages))else:self.errors.append(f"max_turns ({job.max_turns}) reached")- return finish_session(self.s, ok=ok, exit_reason=reason, text=text, usage=self.usage,- tool_calls=self.tool_calls, errors=self.errors, turns=len(self.messages),- nudged=self.nudged, tools=[t.name for t in self.specs])+ return finish_session(+ self.s,+ ok=ok,+ exit_reason=reason,+ text=text,+ usage=self.usage,+ tool_calls=self.tool_calls,+ errors=self.errors,+ turns=len(self.messages),+ nudged=self.nudged,+ tools=[t.name for t in self.specs],+ )def _generate(self, turn: int) -> ChatResponse | None:- req = ChatRequest(messages=self.messages, system=self.system, tools=self.specs,- temperature=self.s.job.api.temperature,- thinking=self.s.job.api.thinking, label=f"api-agent:{self.s.label}:t{turn}")+ req = ChatRequest(+ messages=self.messages,+ system=self.system,+ tools=self.specs,+ temperature=self.s.job.api.temperature,+ thinking=self.s.job.api.thinking,+ label=f"api-agent:{self.s.label}:t{turn}",+ )delay = 2.0for attempt in range(MODEL_RETRIES):try:@@ -183,7 +221,13 @@ class _Loop:return respexcept Exception as e: # ModelError or provider glitchretryable = bool(getattr(e, "retryable", False))- self.s.traj.append("model_error", turn=turn, attempt=attempt, error=str(e)[:2000], retryable=retryable)+ self.s.traj.append(+ "model_error",+ turn=turn,+ attempt=attempt,+ error=str(e)[:2000],+ retryable=retryable,+ )if not retryable or attempt == MODEL_RETRIES - 1:self.errors.append(f"model error on turn {turn}: {type(e).__name__}: {e}")return None@@ -204,13 +248,33 @@ class _Loop:# the read tool, so it is the calibration arm for the atime probe.from codeverse.skills.telemetry import record_exact_read- record_exact_read(self.s.ws.root, str((call.arguments or {}).get("path", "")),- turn=turn, label=getattr(self.s, "label", "") or "")+ record_exact_read(+ self.s.ws.root,+ str((call.arguments or {}).get("path", "")),+ turn=turn,+ label=getattr(self.s, "label", "") or "",+ )if call.name in (BUILD_TOOL, "run_build"):self.last_build_turn = turn- parts.append(ToolResultPart(call_id=call.id, name=call.name, content=out.text, images=out.images, is_error=out.is_error))- self.s.traj.append("tool_result", turn=turn, name=call.name, call_id=call.id, ok=not out.is_error,- content=out.text[:8000], images=[i.path for i in out.images], numbers=out.numbers)+ parts.append(+ ToolResultPart(+ call_id=call.id,+ name=call.name,+ content=out.text,+ images=out.images,+ is_error=out.is_error,+ )+ )+ self.s.traj.append(+ "tool_result",+ turn=turn,+ name=call.name,+ call_id=call.id,+ ok=not out.is_error,+ content=out.text[:8000],+ images=[i.path for i in out.images],+ numbers=out.numbers,+ )self.messages.append(ChatMessage(role="tool", parts=parts))def _dispatch(self, name: str, args: dict[str, Any]) -> ToolOutcome:@@ -222,7 +286,9 @@ class _Loop:return self.files.call(name, args)if self.spatial and name in self.spatial.names():return self.spatial.call(name, args)- return ToolOutcome(f"unknown tool {name!r}; available: {sorted(t.name for t in self.specs)}", is_error=True)+ return ToolOutcome(+ f"unknown tool {name!r}; available: {sorted(t.name for t in self.specs)}", is_error=True+ )def _needs_build_nudge(self) -> bool:has_build = bool(self.spatial and BUILD_TOOL in self.spatial.names())@@ -230,9 +296,11 @@ class _Loop:def _facts(self) -> str:writes = list(dict.fromkeys(self.files.writes))- lines = [f"- tool calls so far: {self.tool_calls}",- f"- files written/edited (in order): {', '.join(writes) if writes else 'none'}",- f"- last build turn: {self.last_build_turn} (last write turn: {self.last_write_turn})"]+ lines = [+ f"- tool calls so far: {self.tool_calls}",+ f"- files written/edited (in order): {', '.join(writes) if writes else 'none'}",+ f"- last build turn: {self.last_build_turn} (last write turn: {self.last_write_turn})",+ ]return "\n".join(lines)diff --git a/harness/codeverse/agents/api_tools.py b/harness/codeverse/agents/api_tools.pyindex a628894b..4c6fc95c 100644--- a/harness/codeverse/agents/api_tools.py+++ b/harness/codeverse/agents/api_tools.py@@ -16,6 +16,7 @@ import fnmatchimport jsonimport osimport shlex+from collections.abc import Collectionfrom dataclasses import dataclass, fieldfrom pathlib import Pathfrom typing import Any@@ -28,16 +29,47 @@ from codeverse.workspace import WorkspaceREAD_CAP_CHARS = 60_000SHELL_OUT_CAP = 6_000SHELL_TIMEOUT_S = 180.0-SHELL_ALLOW = ("node", "python", "python3", "ls", "cat", "head", "tail", "wc", "grep", "find", "stat")+SHELL_ALLOW = (+ "node",+ "python",+ "python3",+ "ls",+ "cat",+ "head",+ "tail",+ "wc",+ "grep",+ "find",+ "stat",+)_SHELL_OPERATORS = {"|", "&&", "||", ";", ">", ">>", "<", "2>", "&"}#: python/node short options that run inline code / a REPL (``-c CODE``, ``-e CODE``, ``-p``, ``-i``)#: or load code by path we cannot vet (``-r``); combined forms (``-Bc``, ``-pe``) are caught per letter._INLINE_SHORT = {"python": set("cim"), "python3": set("cim"), "node": set("epir")}-_INLINE_LONG = ("--eval", "--print", "--interactive", "--input-type", "--require", "--import", "--loader",- "--experimental-loader", "--experimental-default-type")+_INLINE_LONG = (+ "--eval",+ "--print",+ "--interactive",+ "--input-type",+ "--require",+ "--import",+ "--loader",+ "--experimental-loader",+ "--experimental-default-type",+)#: ``python -m <module>`` is allowed only for these stdlib modules (syntax / JSON checks)PY_MODULE_ALLOW = ("py_compile", "compileall", "json.tool", "ast", "tokenize")-_FIND_DENY = ("-exec", "-execdir", "-ok", "-okdir", "-delete", "-fprint", "-fprintf", "-fls", "-fprint0")+_FIND_DENY = (+ "-exec",+ "-execdir",+ "-ok",+ "-okdir",+ "-delete",+ "-fprint",+ "-fprintf",+ "-fls",+ "-fprint0",+)_SKIP_GLOB_DIRS = (".git", "node_modules", "__pycache__", "trajectories")@@ -60,9 +92,32 @@ def _schema(props: dict[str, dict[str, Any]], required: list[str]) -> dict[str,class FileTools:"""read_file / write_file / edit_file / list_files / run_shell inside one workspace."""- def __init__(self, ws: Workspace, write_roots: list[str], *, allow_shell: bool = True):+ def __init__(+ self,+ ws: Workspace,+ write_roots: list[str],+ *,+ allow_shell: bool = True,+ edit_only: Collection[str] | None = None,+ always_writable: Collection[str] = (),+ ):self.ws = wsself.write_roots = [(ws.root / r).resolve() for r in write_roots]+ #: when set, an EXISTING file outside this set may not be overwritten. New files are+ #: fine (a task may add a part) and ``always_writable`` (the entry file) is exempt.+ #:+ #: Why a hard rule and not the prose the prompt already carries ("keep everything else+ #: as it is"): measured 2026-08-25 over 128 judged refine rounds on static objects, the+ #: rounds that REGRESSED the score had rewritten a median 6 of 9 part files against 4+ #: of 8 for the rounds that improved — and their worst-dropping criterion was+ #: structure_plausibility with zero gate errors, i.e. working geometry the task never+ #: named was replaced and nothing deterministic could see it. The prompt was already+ #: asking for scope; only the tool can hold it.+ self.edit_only = (+ frozenset((ws.root / f).resolve() for f in edit_only) if edit_only is not None else None+ )+ self.always_writable = frozenset((ws.root / f).resolve() for f in always_writable)+ self.scope_denials: list[str] = []self.allow_shell = allow_shellself.writes: list[str] = [] # workspace-relative paths written/edited, in order@@ -70,26 +125,71 @@ class FileTools:def specs(self) -> list[ToolSpec]:roots = ", ".join(os.path.relpath(r, self.ws.root) + "/" for r in self.write_roots)specs = [- ToolSpec(name="read_file", description="Read a text file in the workspace (path relative to the workspace root).",- parameters=_schema({"path": {"type": "string", "description": "workspace-relative path"}}, ["path"])),- ToolSpec(name="write_file", description=f"Create or overwrite a text file. Only allowed under: {roots}. Parent dirs are created.",- parameters=_schema({"path": {"type": "string"}, "content": {"type": "string"}}, ["path", "content"])),- ToolSpec(name="edit_file", description=f"Exact-string replacement in an existing file (under {roots}). `old` must occur exactly once unless all=true.",- parameters=_schema({"path": {"type": "string"}, "old": {"type": "string"}, "new": {"type": "string"},- "all": {"type": "boolean", "description": "replace every occurrence", "default": False}},- ["path", "old", "new"])),- ToolSpec(name="list_files", description="List workspace files matching a glob (default '**/*' under src/). Hidden/git/node_modules skipped.",- parameters=_schema({"glob": {"type": "string", "description": "e.g. 'src/**/*.js'", "default": "src/**/*"}}, [])),+ ToolSpec(+ name="read_file",+ description="Read a text file in the workspace (path relative to the workspace root).",+ parameters=_schema(+ {"path": {"type": "string", "description": "workspace-relative path"}}, ["path"]+ ),+ ),+ ToolSpec(+ name="write_file",+ description=f"Create or overwrite a text file. Only allowed under: {roots}. Parent dirs are created.",+ parameters=_schema(+ {"path": {"type": "string"}, "content": {"type": "string"}}, ["path", "content"]+ ),+ ),+ ToolSpec(+ name="edit_file",+ description=f"Exact-string replacement in an existing file (under {roots}). `old` must occur exactly once unless all=true.",+ parameters=_schema(+ {+ "path": {"type": "string"},+ "old": {"type": "string"},+ "new": {"type": "string"},+ "all": {+ "type": "boolean",+ "description": "replace every occurrence",+ "default": False,+ },+ },+ ["path", "old", "new"],+ ),+ ),+ ToolSpec(+ name="list_files",+ description="List workspace files matching a glob (default '**/*' under src/). Hidden/git/node_modules skipped.",+ parameters=_schema(+ {+ "glob": {+ "type": "string",+ "description": "e.g. 'src/**/*.js'",+ "default": "src/**/*",+ }+ },+ [],+ ),+ ),]if self.allow_shell:- specs.append(ToolSpec(- name="run_shell",- description=f"Run ONE command in the workspace root (no pipes/redirects/network). Allowed programs: {', '.join(SHELL_ALLOW)}. "- "Use it to syntax-check (`node --check src/x.js`, `python -m py_compile src/model.py`) or inspect files. "- "Inline code (`python -c`, `node -e`) and paths outside the workspace are rejected.",- parameters=_schema({"cmd": {"type": "string", "description": "the command line, e.g. 'node --check src/object.js'"},- "timeout_s": {"type": "integer", "default": 60}}, ["cmd"]),- ))+ specs.append(+ ToolSpec(+ name="run_shell",+ description=f"Run ONE command in the workspace root (no pipes/redirects/network). Allowed programs: {', '.join(SHELL_ALLOW)}. "+ "Use it to syntax-check (`node --check src/x.js`, `python -m py_compile src/model.py`) or inspect files. "+ "Inline code (`python -c`, `node -e`) and paths outside the workspace are rejected.",+ parameters=_schema(+ {+ "cmd": {+ "type": "string",+ "description": "the command line, e.g. 'node --check src/object.js'",+ },+ "timeout_s": {"type": "integer", "default": 60},+ },+ ["cmd"],+ ),+ )+ )return specsdef names(self) -> set[str]:@@ -97,8 +197,13 @@ class FileTools:# ------------------------------------------------------------------ dispatchdef call(self, name: str, args: dict[str, Any]) -> ToolOutcome:- fn = {"read_file": self.read_file, "write_file": self.write_file, "edit_file": self.edit_file,- "list_files": self.list_files, "run_shell": self.run_shell}.get(name)+ fn = {+ "read_file": self.read_file,+ "write_file": self.write_file,+ "edit_file": self.edit_file,+ "list_files": self.list_files,+ "run_shell": self.run_shell,+ }.get(name)if fn is None or (name == "run_shell" and not self.allow_shell):return ToolOutcome(f"unknown tool {name!r}", is_error=True)try:@@ -126,6 +231,24 @@ class FileTools:if write and not any(p == r or r in p.parents for r in self.write_roots):roots = ", ".join(os.path.relpath(r, root) + "/" for r in self.write_roots)raise PathDenied(f"writes are only allowed under {roots} (got {path})")+ if (+ write+ and self.edit_only is not None+ and p.exists()+ and p not in self.edit_only+ and p not in self.always_writable+ ):+ rel = os.path.relpath(p, root)+ self.scope_denials.append(rel)+ allowed = (+ ", ".join(sorted(os.path.relpath(f, root) for f in self.edit_only)) or "(none)"+ )+ raise PathDenied(+ f"{rel} is outside this task's scope and already exists — it is another part's file "+ f"and this round did not ask for changes to it. You may edit: {allowed}; you may also "+ f"create NEW files and edit the entry file. If the fix genuinely needs {rel}, say so "+ f"in your final summary instead of editing it."+ )return p# ------------------------------------------------------------------ tools@@ -145,7 +268,9 @@ class FileTools:p.write_text(content)rel = os.path.relpath(p, self.ws.root)self.writes.append(rel)- return ToolOutcome(f"{'overwrote' if existed else 'created'} {rel} ({len(content)} chars, {content.count(chr(10)) + 1} lines)")+ return ToolOutcome(+ f"{'overwrote' if existed else 'created'} {rel} ({len(content)} chars, {content.count(chr(10)) + 1} lines)"+ )def edit_file(self, path: str, old: str, new: str, all: bool = False) -> ToolOutcome: # noqa: A002 - API namep = self._resolve(path, write=True)@@ -154,15 +279,25 @@ class FileTools:try:text = p.read_text(encoding="utf-8")except UnicodeDecodeError:- return ToolOutcome(f"{path} is not UTF-8 text; edit_file only works on text files (use write_file to replace it)",- is_error=True)+ return ToolOutcome(+ f"{path} is not UTF-8 text; edit_file only works on text files (use write_file to replace it)",+ is_error=True,+ )n = text.count(old)if not old:- return ToolOutcome("`old` must be non-empty; read the file and quote the exact text to replace", is_error=True)+ return ToolOutcome(+ "`old` must be non-empty; read the file and quote the exact text to replace",+ is_error=True,+ )if n == 0:- return ToolOutcome(f"`old` not found in {path}; read_file it and copy the exact text", is_error=True)+ return ToolOutcome(+ f"`old` not found in {path}; read_file it and copy the exact text", is_error=True+ )if n > 1 and not all:- return ToolOutcome(f"`old` occurs {n} times in {path}; include more context or pass all=true", is_error=True)+ return ToolOutcome(+ f"`old` occurs {n} times in {path}; include more context or pass all=true",+ is_error=True,+ )p.write_text(text.replace(old, new) if all else text.replace(old, new, 1))rel = os.path.relpath(p, self.ws.root)self.writes.append(rel)@@ -175,7 +310,9 @@ class FileTools:if not p.is_file():continuerel = p.relative_to(root).as_posix()- if any(part in _SKIP_GLOB_DIRS or part.startswith(".") for part in Path(rel).parts[:-1]):+ if any(+ part in _SKIP_GLOB_DIRS or part.startswith(".") for part in Path(rel).parts[:-1]+ ):continueif fnmatch.fnmatch(rel, glob) or fnmatch.fnmatch(rel, glob.replace("**/", "")):out.append(f"{rel} ({p.stat().st_size} B)")@@ -232,19 +369,35 @@ class FileTools:argv = shlex.split(cmd)except ValueError as e:return ToolOutcome(f"cannot parse command: {e}", is_error=True)- if any(tok in _SHELL_OPERATORS for tok in argv): # no shell is involved; this is just a clear message- return ToolOutcome("shell operators (| && ; > <) are not allowed; run ONE plain command", is_error=True)+ if any(+ tok in _SHELL_OPERATORS for tok in argv+ ): # no shell is involved; this is just a clear message+ return ToolOutcome(+ "shell operators (| && ; > <) are not allowed; run ONE plain command", is_error=True+ )why = self._shell_policy_error(argv)if why:return ToolOutcome(why, is_error=True)env = {- "PATH": os.environ.get("PATH", "/usr/bin:/bin"), "HOME": str(self.ws.root), "LANG": "C.UTF-8",- "NODE_PATH": str(get_settings().runtime_js_dir() / "node_modules"), "PYTHONDONTWRITEBYTECODE": "1",- "NO_PROXY": "*", "no_proxy": "*",+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),+ "HOME": str(self.ws.root),+ "LANG": "C.UTF-8",+ "NODE_PATH": str(get_settings().runtime_js_dir() / "node_modules"),+ "PYTHONDONTWRITEBYTECODE": "1",+ "NO_PROXY": "*",+ "no_proxy": "*",}t = float(max(5, min(_as_int(timeout_s, 60), int(SHELL_TIMEOUT_S))))- proc = run_with_watchdog(argv, cwd=self.ws.root, env=env, soft_timeout_s=t, idle_grace_s=5, hard_timeout_s=t + 5,- activity_dirs=[], poll_s=0.2)+ proc = run_with_watchdog(+ argv,+ cwd=self.ws.root,+ env=env,+ soft_timeout_s=t,+ idle_grace_s=5,+ hard_timeout_s=t + 5,+ activity_dirs=[],+ poll_s=0.2,+ )body = f"$ {cmd}\nrc={proc.rc}" + (" (killed: timeout)" if proc.timed_out else "")if proc.stdout.strip():body += "\n--- stdout ---\n" + _cap(proc.stdout)@@ -274,11 +427,16 @@ class SpatialTools:def __init__(self, ws: Workspace, *, track: str = "", language: str = "", round_index: int = 0):from codeverse.spatial.registry import ToolContext, list_tools- self.ctx = ToolContext(workspace=ws, round_index=round_index, language=language, track=track)+ self.ctx = ToolContext(+ workspace=ws, round_index=round_index, language=language, track=track+ )self.tools = {t.name: t for t in list_tools(track=track, language=language)}def specs(self) -> list[ToolSpec]:- return [ToolSpec(name=t.name, description=t.description, parameters=t.schema()) for t in self.tools.values()]+ return [+ ToolSpec(name=t.name, description=t.description, parameters=t.schema())+ for t in self.tools.values()+ ]def names(self) -> set[str]:return set(self.tools)@@ -295,4 +453,11 @@ class SpatialTools:return ToolOutcome(text, images=images, is_error=not obs.ok, numbers=obs.numbers)-__all__ = ["FileTools", "SpatialTools", "ToolOutcome", "PathDenied", "SHELL_ALLOW", "PY_MODULE_ALLOW"]+__all__ = [+ "FileTools",+ "SpatialTools",+ "ToolOutcome",+ "PathDenied",+ "SHELL_ALLOW",+ "PY_MODULE_ALLOW",+]diff --git a/harness/codeverse/contracts/agent.py b/harness/codeverse/contracts/agent.pyindex 19ed0bb3..00fe694d 100644--- a/harness/codeverse/contracts/agent.py+++ b/harness/codeverse/contracts/agent.py@@ -19,7 +19,9 @@ class FileChange(BaseModel):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)")+ max_usd: float = Field(+ default=0.0, description="stop the session when its own cost exceeds this (0 = no cap)"+ )temperature: float = 0.3thinking: str = "low"allow_shell: bool = True@@ -39,12 +41,18 @@ class AgentJob(BaseModel):timeout_s: int = 1800max_turns: int = 60allow_network: bool = False- 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")+ 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)# ------------------------------------------------------------- typed job contextround: int = Field(default=0, description="round index → trajectory dir + ToolContext")- kind: str = Field(default="", description="task kind: baseline | refine | repair | asset | zone ...")+ 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(@@ -52,9 +60,23 @@ class AgentJob(BaseModel):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")+ edit_only: bool = Field(+ default=False,+ description="ENFORCE files_hint: an existing file outside it cannot be overwritten (new files "+ "and the language entry file stay allowed). Refine tasks set this so a session fixing one "+ "part cannot rewrite its neighbours.",+ )+ always_writable: list[str] = Field(+ default_factory=list,+ description="files exempt from edit_only (the entry file: adding a part means importing it there)",+ )+ 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)")+ extra: dict[str, Any] = Field(+ default_factory=dict, description="one-off backend hints (legacy keys are lifted)"+ )@model_validator(mode="before")@classmethoddiff --git a/harness/codeverse/prompts/tracks/refine_object.j2 b/harness/codeverse/prompts/tracks/refine_object.j2index 7f599ab7..8cd3dfe3 100644--- a/harness/codeverse/prompts/tracks/refine_object.j2+++ b/harness/codeverse/prompts/tracks/refine_object.j2@@ -10,7 +10,9 @@ THIS round. Make exactly these changes, keep everything else as it is, and keepTargets: {{ targets | join(', ') }}{% if edit_only_these %}-EDIT ONLY THESE FILES (other tasks edit other files in parallel — touching anything else causes conflicts):+EDIT ONLY THESE FILES — the write tool refuses to overwrite any other existing part file this round.+You may still create new files and edit the entry file (to import a new part). If a fix truly needs a+file outside this list, finish without it and say so in your summary.{% for f in files %}- `{{ f }}`{% endfor %}{% else %}diff --git a/harness/codeverse/tracks/generation.py b/harness/codeverse/tracks/generation.pyindex 0af05ab3..c0f63ead 100644--- a/harness/codeverse/tracks/generation.py+++ b/harness/codeverse/tracks/generation.py@@ -116,8 +116,12 @@ class GenerationTask(BaseModel):label: strprompt: str- system: str = Field(default="", description="system prompt (single-shot) / system_append (agent)")- files_hint: list[str] = Field(default_factory=list, description="files this task should produce/edit")+ system: str = Field(+ default="", description="system prompt (single-shot) / system_append (agent)"+ )+ files_hint: list[str] = Field(+ default_factory=list, description="files this task should produce/edit"+ )round: int = 0kind: str = "generate"images: list[ImagePart] = Field(default_factory=list)@@ -125,13 +129,24 @@ class GenerationTask(BaseModel):thinking: str = "medium"max_output_tokens: int = 32000timeout_s: int | None = None- max_turns: int = Field(default=0, description="model turns for an agent session (0 = the harness default)")+ max_turns: int = Field(+ default=0, description="model turns for an agent session (0 = the harness default)"+ )write_roots: list[str] = Field(default_factory=lambda: ["src", "public"])- phase: int = Field(default=0, ge=0, description=(- "execution phase inside ONE round: tasks run in parallel WITHIN a phase and phases run "- "in ascending order. Everything is phase 0 unless a track says otherwise — the only "- "current user is per-part scoped generation, where the assembly session (phase 1) must "- "see the part files the scoped sessions (phase 0) wrote."))+ edit_only: bool = Field(+ default=False,+ description="enforce files_hint as the only existing files this session may overwrite",+ )+ phase: int = Field(+ default=0,+ ge=0,+ description=(+ "execution phase inside ONE round: tasks run in parallel WITHIN a phase and phases run "+ "in ascending order. Everything is phase 0 unless a track says otherwise — the only "+ "current user is per-part scoped generation, where the assembly session (phase 1) must "+ "see the part files the scoped sessions (phase 0) wrote."+ ),+ )class GenerationResult(BaseModel):@@ -143,9 +158,15 @@ class GenerationResult(BaseModel):text: str = Field(default="", description="model/agent final text (truncated)")transcript_path: str = ""label: str = ""- turns: int = Field(default=0, description="turns the agent session(s) took, as the backend counts them")- sessions: int = Field(default=0, description="agent sessions run for this task (retry / wrap-up count)")- turn_capped: bool = Field(default=False, description="a session hit the turn budget and was wrapped up")+ turns: int = Field(+ default=0, description="turns the agent session(s) took, as the backend counts them"+ )+ sessions: int = Field(+ default=0, description="agent sessions run for this task (retry / wrap-up count)"+ )+ turn_capped: bool = Field(+ default=False, description="a session hit the turn budget and was wrapped up"+ )# ----------------------------------------------------------------------------- git helpers@@ -163,7 +184,9 @@ def workspace_lock(ws: Workspace) -> threading.Lock:return lock-def changed_files_safe(ws: Workspace, since: str | None = None, *, retries: int = 6) -> list[FileChange]:+def changed_files_safe(+ ws: Workspace, since: str | None = None, *, retries: int = 6+) -> list[FileChange]:"""``ws.changed_files`` serialised per workspace and retried on transient git index locks."""with workspace_lock(ws):for attempt in range(retries):@@ -185,7 +208,7 @@ def is_single_shot(agent_id: str) -> bool:def single_shot_model_id(agent_id: str) -> str:if not is_single_shot(agent_id):raise ValueError(f"not a single-shot id: {agent_id!r}")- return agent_id[len(SINGLE_SHOT_PREFIX):]+ return agent_id[len(SINGLE_SHOT_PREFIX) :]def single_shot_format_text() -> str:@@ -226,7 +249,12 @@ def generate_files(# cut off by max_output_tokens: the envelope is unterminated — one retry with# a doubled budget beats writing a half-file and burning repair attempts on itif events is not None:- events.emit("generate.truncated", label=task.label, finish_reason=str(resp.finish_reason), retry=True)+ events.emit(+ "generate.truncated",+ label=task.label,+ finish_reason=str(resp.finish_reason),+ retry=True,+ )req = req.model_copy(update={"max_output_tokens": min(task.max_output_tokens * 2, 65536)})resp = model.generate(req)usage = usage + resp.usage@@ -236,16 +264,33 @@ def generate_files((traj / "response.md").write_text(resp.text or "")if _is_truncated(resp):if events is not None:- events.emit("generate.truncated", label=task.label, finish_reason=str(resp.finish_reason), retry=False)- return GenerationResult(ok=False, usage=usage, notes=f"truncated: finish_reason={resp.finish_reason}",- text=(resp.text or "")[:2000], transcript_path=str(traj / "response.md"), label=task.label)+ events.emit(+ "generate.truncated",+ label=task.label,+ finish_reason=str(resp.finish_reason),+ retry=False,+ )+ return GenerationResult(+ ok=False,+ usage=usage,+ notes=f"truncated: finish_reason={resp.finish_reason}",+ text=(resp.text or "")[:2000],+ transcript_path=str(traj / "response.md"),+ label=task.label,+ )try:files = parse_multifile(resp.text or "", expected_files=task.files_hint or None)except MultiFileParseError as e:if events is not None:events.emit("generate.parse_failed", label=task.label, error=str(e))- return GenerationResult(ok=False, usage=usage, notes=f"parse failed: {e}", text=(resp.text or "")[:2000],- transcript_path=str(traj / "response.md"), label=task.label)+ return GenerationResult(+ ok=False,+ usage=usage,+ notes=f"parse failed: {e}",+ text=(resp.text or "")[:2000],+ transcript_path=str(traj / "response.md"),+ label=task.label,+ )skipped: list[str] = []def _skip(path: str, reason: str) -> None:@@ -255,16 +300,34 @@ def generate_files(changes = write_files(ws, files, allowed_roots=allowed_roots, on_skip=_skip)if events is not None:- events.emit("generate.done", label=task.label, strategy="single-shot", files=[c.path for c in changes],- cost_usd=round(usage.cost_usd, 4))+ events.emit(+ "generate.done",+ label=task.label,+ strategy="single-shot",+ files=[c.path for c in changes],+ cost_usd=round(usage.cost_usd, 4),+ )notes = f"skipped out-of-root paths: {', '.join(skipped)}" if skipped else ""- return GenerationResult(ok=bool(changes), usage=usage, files_changed=changes, notes=notes,- text=(resp.text or "")[:2000], transcript_path=str(traj / "response.md"), label=task.label)+ return GenerationResult(+ ok=bool(changes),+ usage=usage,+ files_changed=changes,+ notes=notes,+ text=(resp.text or "")[:2000],+ transcript_path=str(traj / "response.md"),+ label=task.label,+ )#: task kinds whose money belongs to a differently-named stage of the cost vocabulary-_STAGE_FOR_KIND = {"rebuild": "repair", "asset_fix": "assets", "asset": "assets",- "zone": "zones", "generate": "baseline", "compose": "assemble"}+_STAGE_FOR_KIND = {+ "rebuild": "repair",+ "asset_fix": "assets",+ "asset": "assets",+ "zone": "zones",+ "generate": "baseline",+ "compose": "assemble",+}def task_stage(task: GenerationTask) -> str:@@ -281,12 +344,20 @@ def task_stage(task: GenerationTask) -> str:return task.label or stage or "other"-def _charge(budget: Any | None, usage: Usage, *, task: GenerationTask, label: str, outcome: str = "ok") -> None:+def _charge(+ budget: Any | None, usage: Usage, *, task: GenerationTask, label: str, outcome: str = "ok"+) -> None:"""Spend through the guard with the stage/label/round this task belongs to."""if budget is None:return- budget.charge(usage, stage=task_stage(task), role="generator", label=label,- round_index=task.round, outcome=outcome)+ budget.charge(+ usage,+ stage=task_stage(task),+ role="generator",+ label=label,+ round_index=task.round,+ outcome=outcome,+ )_TRUNCATED_FINISH = {"max_tokens", "max_output_tokens", "length"}@@ -335,14 +406,32 @@ def run_agent_task(except Exception: # noqa: BLE001 — best effort context onlypass# extra mirrors the typed fields until every agent backend reads job.round/… directly- extra: dict[str, Any] = {"round": task.round, "kind": task.kind, "files_hint": list(task.files_hint),- "language": language, "track": track}- job = AgentJob(workspace=str(ws.root), prompt=task.prompt, system_append=task.system,- model=getattr(agent, "model", ""), label=task.label, timeout_s=timeout,- spatial_tools=True, write_roots=task.write_roots,- round=task.round, kind=task.kind, language=language, track=track,- files_hint=list(task.files_hint), extra=extra,- **({"max_turns": turns_cap} if turns_cap > 0 else {}))+ extra: dict[str, Any] = {+ "round": task.round,+ "kind": task.kind,+ "files_hint": list(task.files_hint),+ "language": language,+ "track": track,+ }+ job = AgentJob(+ workspace=str(ws.root),+ prompt=task.prompt,+ system_append=task.system,+ model=getattr(agent, "model", ""),+ label=task.label,+ timeout_s=timeout,+ spatial_tools=True,+ write_roots=task.write_roots,+ round=task.round,+ kind=task.kind,+ language=language,+ track=track,+ files_hint=list(task.files_hint),+ extra=extra,+ edit_only=task.edit_only,+ always_writable=_always_writable(language),+ **({"max_turns": turns_cap} if turns_cap > 0 else {}),+ )acc = _SessionAcc(task=task, budget=budget)res = acc.run(agent, job)changes = res.files_changed or _attributed_fallback(ws, task, before)@@ -352,19 +441,36 @@ def run_agent_task(if events is not None:# NB: not ``cost_usd`` — an event carrying that key is priced as its own# call by ``cost.reconstruct``, and this money is already in the session row.- events.emit("generate.turn_cap", label=task.label, round=task.round, max_turns=job.max_turns,- turns=acc.turns, session_usd=round(acc.usage.cost_usd, 4))- wrap = job.model_copy(update={"prompt": WRAPUP_PROMPT + task.prompt,- "max_turns": max(2, int(wrapup_turns))})+ events.emit(+ "generate.turn_cap",+ label=task.label,+ round=task.round,+ max_turns=job.max_turns,+ turns=acc.turns,+ session_usd=round(acc.usage.cost_usd, 4),+ )+ wrap = job.model_copy(+ update={"prompt": WRAPUP_PROMPT + task.prompt, "max_turns": max(2, int(wrapup_turns))}+ )res = acc.run(agent, wrap, wrapup=True, optional=True) or reschanges = res.files_changed or changes or _attributed_fallback(ws, task, before)- if retry_silent_bail and not changes and not acc.wrapped and res.exit_reason not in ("timeout", "budget"):+ if (+ retry_silent_bail+ and not changes+ and not acc.wrapped+ and res.exit_reason not in ("timeout", "budget")+ ):if events is not None:events.emit("generate.silent_bail", label=task.label, exit_reason=res.exit_reason)- job2 = job.model_copy(update={"prompt": (- "Your previous attempt ended WITHOUT writing any file. You must create/edit the files "- "described below and run the build tool before finishing.\n\n" + task.prompt)})+ job2 = job.model_copy(+ update={+ "prompt": (+ "Your previous attempt ended WITHOUT writing any file. You must create/edit the files "+ "described below and run the build tool before finishing.\n\n" + task.prompt+ )+ }+ )res = acc.run(agent, job2, optional=True) or reschanges = res.files_changed or _attributed_fallback(ws, task, before)@@ -373,13 +479,30 @@ def run_agent_task(if acc.wrapped:notes += f"; turn cap {job.max_turns} reached → wrap-up session"if events is not None:- events.emit("generate.done", label=task.label, strategy=getattr(agent, "kind", "agent"),- files=[c.path for c in changes], ok=bool(changes), exit_reason=res.exit_reason,- turns=acc.turns, sessions=acc.sessions, turn_capped=acc.wrapped,- cost_usd=round(acc.usage.cost_usd, 4))- return GenerationResult(ok=bool(changes), usage=acc.usage, files_changed=changes, notes=notes,- text=(res.text or "")[:2000], transcript_path=res.transcript_path, label=task.label,- turns=acc.turns, sessions=acc.sessions, turn_capped=acc.wrapped)+ events.emit(+ "generate.done",+ label=task.label,+ strategy=getattr(agent, "kind", "agent"),+ files=[c.path for c in changes],+ ok=bool(changes),+ exit_reason=res.exit_reason,+ turns=acc.turns,+ sessions=acc.sessions,+ turn_capped=acc.wrapped,+ cost_usd=round(acc.usage.cost_usd, 4),+ )+ return GenerationResult(+ ok=bool(changes),+ usage=acc.usage,+ files_changed=changes,+ notes=notes,+ text=(res.text or "")[:2000],+ transcript_path=res.transcript_path,+ label=task.label,+ turns=acc.turns,+ sessions=acc.sessions,+ turn_capped=acc.wrapped,+ )class _SessionAcc:@@ -399,13 +522,17 @@ class _SessionAcc:self.wrapped = Falseself.errors: list[str] = []- def run(self, agent: Any, job: AgentJob, *, wrapup: bool = False, optional: bool = False) -> AgentResult | None:+ def run(+ self, agent: Any, job: AgentJob, *, wrapup: bool = False, optional: bool = False+ ) -> AgentResult | None:"""One session. ``optional`` sessions (wrap-up, silent-bail retry) nevertake the task down: a crash there leaves the earlier, already chargedsession as the result instead of discarding money that was really spent."""self.sessions += 1self.wrapped = self.wrapped or wrapup- label = self.task.label + (".wrapup" if wrapup else (f".a{self.sessions}" if self.sessions > 1 else ""))+ label = self.task.label + (+ ".wrapup" if wrapup else (f".a{self.sessions}" if self.sessions > 1 else "")+ )try:res: AgentResult = agent.run(job)except Exception as e: # noqa: BLE001 — a budget stop still propagates (see below)@@ -423,8 +550,14 @@ class _SessionAcc:def charge(self, usage: Usage, *, label: str, outcome: str) -> None:if self.budget is None or not (usage.cost_usd or usage.input_tokens or usage.output_tokens):return- self.budget.charge(usage, stage=task_stage(self.task), role="generator",- label=label, round_index=self.task.round, outcome=outcome)+ self.budget.charge(+ usage,+ stage=task_stage(self.task),+ role="generator",+ label=label,+ round_index=self.task.round,+ outcome=outcome,+ )def _is_budget_stop(e: BaseException) -> bool:@@ -457,6 +590,16 @@ def session_turns(res: Any) -> int:return 0+def _always_writable(language: str) -> list[str]:+ """The entry file is exempt from ``edit_only``: adding a part means importing it there."""+ from codeverse.contracts.common import ENTRY_FILE, Language++ try:+ return [ENTRY_FILE[Language(language)]]+ except (ValueError, KeyError):+ return []++def _attributed_fallback(ws: Workspace, task: GenerationTask, before: str) -> list[FileChange]:"""Change detection when the agent did not report its own ``files_changed``.@@ -468,7 +611,9 @@ def _attributed_fallback(ws: Workspace, task: GenerationTask, before: str) -> lifrom codeverse.agents.cli_common import attribute_changesexcept ImportError: # pragma: no cover — agents package always ships with tracksreturn raw- return attribute_changes(raw, write_roots=list(task.write_roots), own_hints=frozenset(task.files_hint))+ return attribute_changes(+ raw, write_roots=list(task.write_roots), own_hints=frozenset(task.files_hint)+ )def generate(@@ -495,13 +640,27 @@ def generate(if model is None:factory = model_factory or _default_model_factorymodel = factory(single_shot_model_id(agent_id))- return generate_files(ws, model=model, task=task, budget=budget, events=events,- allowed_roots=tuple(r.rstrip("/") + "/" for r in task.write_roots))+ return generate_files(+ ws,+ model=model,+ task=task,+ budget=budget,+ events=events,+ allowed_roots=tuple(r.rstrip("/") + "/" for r in task.write_roots),+ )if agent is None:factory = agent_factory or _default_agent_factoryagent = factory(agent_id)- return run_agent_task(ws, agent=agent, task=task, settings=settings, budget=budget, events=events,- max_turns=max_turns, wrapup_turns=wrapup_turns)+ return run_agent_task(+ ws,+ agent=agent,+ task=task,+ settings=settings,+ budget=budget,+ events=events,+ max_turns=max_turns,+ wrapup_turns=wrapup_turns,+ )def _default_model_factory(model_id: str) -> Any:diff --git a/harness/codeverse/tracks/static_object.py b/harness/codeverse/tracks/static_object.pyindex 1ef5fb60..6d38b1ba 100644--- a/harness/codeverse/tracks/static_object.py+++ b/harness/codeverse/tracks/static_object.py@@ -61,13 +61,19 @@ class ObjectPipeline:def measure(self, ctx: RunContext, build: BuildResult) -> Measurement | None:return ctx.services.measure(Path(build.glb_path)) if build.glb_path else None- def gates(self, ctx: RunContext, round_index: int, build: BuildResult, measurement: Measurement | None) -> list[GateReport]:+ def gates(+ self, ctx: RunContext, round_index: int, build: BuildResult, measurement: Measurement | None+ ) -> list[GateReport]:out: list[GateReport] = []glb = Path(build.glb_path) if build.glb_path else Noneif glb is not None:- out.append(ctx.services.connectivity(glb, ctx.language.value)) # fix hints in the author's frame+ out.append(+ ctx.services.connectivity(glb, ctx.language.value)+ ) # fix hints in the author's frameif measurement is not None and ctx.plan is not None:- out.append(ctx.services.contract(measurement, ctx.plan, BBOX_TOLERANCE_M, ctx.language.value))+ out.append(+ ctx.services.contract(measurement, ctx.plan, BBOX_TOLERANCE_M, ctx.language.value)+ )extra = getattr(ctx.runtime, "extra_gates", None)if callable(extra):out.extend(extra(ctx.ws, build))@@ -77,21 +83,38 @@ class ObjectPipeline:out.append(budget_gate(measurement, build, budget_for(ctx)))# a DETAIL round promised not to move anything: prove it in code, not with the judgeif measurement is not None and ctx.extra.get("detail_round") == round_index:- out.append(drift_gate(ctx.extra.get("detail_baseline"), measurement,- tol_m=ctx.policy.detail_bbox_tol_m, language=ctx.language.value))+ out.append(+ drift_gate(+ ctx.extra.get("detail_baseline"),+ measurement,+ tol_m=ctx.policy.detail_bbox_tol_m,+ language=ctx.language.value,+ )+ )return out- def render(self, ctx: RunContext, round_index: int, build: BuildResult, measurement: Measurement | None) -> RenderSet:+ def render(+ self, ctx: RunContext, round_index: int, build: BuildResult, measurement: Measurement | None+ ) -> RenderSet:r = ctx.settings.render- return ctx.services.render_object(Path(build.glb_path), ctx.ws.renders_dir(round_index), views=self.views,- width=r.width, height=r.height)-- def post_render_gates(self, ctx: RunContext, round_index: int, renders: RenderSet) -> list[GateReport]:+ return ctx.services.render_object(+ Path(build.glb_path),+ ctx.ws.renders_dir(round_index),+ views=self.views,+ width=r.width,+ height=r.height,+ )++ def post_render_gates(+ self, ctx: RunContext, round_index: int, renders: RenderSet+ ) -> list[GateReport]:"""Reference-image runs: front-view outline IoU vs the target image (WARN finding with the number)."""gate = silhouette_gate(ctx, renders)return [gate] if gate is not None else []- def geometry_views(self, ctx: RunContext, round_index: int, build: BuildResult) -> RenderSet | None:+ def geometry_views(+ self, ctx: RunContext, round_index: int, build: BuildResult+ ) -> RenderSet | None:"""4 clay views for the judge's geometry montage (holes, intersections).The plain-geometry render exposes defects that materials hide; cached, so@@ -103,21 +126,32 @@ class ObjectPipeline:return ctx.services.render_geometry(Path(build.glb_path), out_dir, views=GEOMETRY_VIEWS)except Exception as e: # noqa: BLE001 — optional judge context, never round-fatallog.warning("clay geometry render failed: %s", e)- ctx.events.emit("render.geometry_failed", round=round_index, error=f"{type(e).__name__}: {e}")+ ctx.events.emit(+ "render.geometry_failed", round=round_index, error=f"{type(e).__name__}: {e}"+ )return Nonedef plan_summary(self, ctx: RunContext) -> str:plan = ctx.planif plan is None:return ""- parts = ", ".join(f"{p.name}×{p.instances}" if p.instances > 1 else p.name for p in plan.parts)+ parts = ", ".join(+ f"{p.name}×{p.instances}" if p.instances > 1 else p.name for p in plan.parts+ )# reorder into the measurement table's frame (W×H×D, Y-up): the (x,|z|,y) swap is# self-inverse for extents, so Z-up plans (W,D,H) → (W,H,D), threejs is identity —# otherwise the judge compares the digest position-wise against swapped numbers.e = glb_to_plan_frame(plan.overall_bbox.extents, ctx.language, extents=True)return f"{plan.object_name}: {plan.summary} Overall {e[0]:.2f}×{e[1]:.2f}×{e[2]:.2f} m (W×H×D). Parts: {parts}."- def judge_context(self, ws: Workspace, plan: Plan | None, round_index: int, build: BuildResult, gates: list[GateReport]) -> str:+ def judge_context(+ self,+ ws: Workspace,+ plan: Plan | None,+ round_index: int,+ build: BuildResult,+ gates: list[GateReport],+ ) -> str:return ""@@ -141,11 +175,29 @@ class StaticObjectTrack(BaseTrack):if scoped:return scopedfiles = expected_files(ctx)- prompt = render(self.generate_template, **base_prompt_context(- ctx, expected_files=files, skeleton_files=skeleton_files(ctx) if ctx.single_shot else {}, previous_error=""))+ prompt = render(+ self.generate_template,+ **base_prompt_context(+ ctx,+ expected_files=files,+ skeleton_files=skeleton_files(ctx) if ctx.single_shot else {},+ previous_error="",+ ),+ )ctx.record_prompt("generate", prompt)- return [GenerationTask(label="baseline", prompt=prompt, system=self.system_prompt(ctx), files_hint=files, round=0,- kind="baseline", temperature=0.5, thinking="medium", images=reference_images(ctx))]+ return [+ GenerationTask(+ label="baseline",+ prompt=prompt,+ system=self.system_prompt(ctx),+ files_hint=files,+ round=0,+ kind="baseline",+ temperature=0.5,+ thinking="medium",+ images=reference_images(ctx),+ )+ ]# ------------------------------------------------------------------ scoped baselinedef scopes(self, ctx: RunContext) -> list[PartScope]:@@ -159,8 +211,11 @@ class StaticObjectTrack(BaseTrack):cached = ctx.extra.get("scopes")if isinstance(cached, list):return cached- got = scope_groups(ctx.plan, files_for=file_for_target_factory(ctx),- max_groups=max(2, int(getattr(ctx.settings.limits, "max_parallel_agents", 6) or 6)))+ got = scope_groups(+ ctx.plan,+ files_for=file_for_target_factory(ctx),+ max_groups=max(2, int(getattr(ctx.settings.limits, "max_parallel_agents", 6) or 6)),+ )ctx.extra["scopes"] = gotreturn got@@ -187,30 +242,65 @@ class StaticObjectTrack(BaseTrack):tasks: list[GenerationTask] = []for scope in scopes:files = list(scope.files)- prompt = render(self.part_template, **scope_context(ctx, scope, files=files, expected_files=files))+ prompt = render(+ self.part_template, **scope_context(ctx, scope, files=files, expected_files=files)+ )ctx.record_prompt("generate", prompt)- tasks.append(GenerationTask(- label=f"baseline_{scope.label}", prompt=prompt, system=self.scope_system_prompt(ctx, scope),- files_hint=files, round=0, kind="baseline", phase=0, temperature=0.5, thinking="medium", images=images))+ tasks.append(+ GenerationTask(+ label=f"baseline_{scope.label}",+ prompt=prompt,+ system=self.scope_system_prompt(ctx, scope),+ files_hint=files,+ round=0,+ kind="baseline",+ phase=0,+ temperature=0.5,+ thinking="medium",+ images=images,+ )+ )entry = self.entry_files(ctx)- assemble = render(self.assemble_template, **base_prompt_context(ctx, files=entry, expected_files=entry))+ assemble = render(+ self.assemble_template, **base_prompt_context(ctx, files=entry, expected_files=entry)+ )ctx.record_prompt("assemble", assemble)- tasks.append(GenerationTask(- label="assemble", prompt=assemble, system=self.system_prompt(ctx), files_hint=entry, round=0,- kind="baseline", phase=1, temperature=0.3, thinking="high", images=images))- ctx.events.emit("generate.scoped", round=0, n_scopes=len(scopes), n_parts=sum(len(s.parts) for s in scopes),- scopes=[{"label": s.label, "parts": s.names, "files": list(s.files)} for s in scopes])+ tasks.append(+ GenerationTask(+ label="assemble",+ prompt=assemble,+ system=self.system_prompt(ctx),+ files_hint=entry,+ round=0,+ kind="baseline",+ phase=1,+ temperature=0.3,+ thinking="high",+ images=images,+ )+ )+ ctx.events.emit(+ "generate.scoped",+ round=0,+ n_scopes=len(scopes),+ n_parts=sum(len(s.parts) for s in scopes),+ scopes=[{"label": s.label, "parts": s.names, "files": list(s.files)} for s in scopes],+ )return tasksdef scope_system_prompt(self, ctx: RunContext, scope: PartScope) -> str:- return (f"You are an expert {ctx.language.value} 3D modeller writing RAW code (no SDKs, no helper libraries). "- f"You own {len(scope.parts)} part(s) of a larger object: {', '.join(scope.names)}. "- f"Other sessions own the rest — never write a file outside your list. "- f"Follow the contract exactly; exact numbers beat adjectives; real detail beats a correctly sized box.")+ return (+ f"You are an expert {ctx.language.value} 3D modeller writing RAW code (no SDKs, no helper libraries). "+ f"You own {len(scope.parts)} part(s) of a larger object: {', '.join(scope.names)}. "+ f"Other sessions own the rest — never write a file outside your list. "+ f"Follow the contract exactly; exact numbers beat adjectives; real detail beats a correctly sized box."+ )def system_prompt(self, ctx: RunContext) -> str:- return (f"You are an expert {ctx.language.value} 3D modeller writing RAW code (no SDKs, no helper libraries). "- f"Follow the contract exactly; exact numbers beat adjectives.")+ return (+ f"You are an expert {ctx.language.value} 3D modeller writing RAW code (no SDKs, no helper libraries). "+ f"Follow the contract exactly; exact numbers beat adjectives."+ )def round_files_hint(self, ctx: RunContext) -> list[str]:return expected_files(ctx)@@ -226,20 +316,46 @@ class StaticObjectTrack(BaseTrack):# which runs only once the structure gates are clean.return reference_refine_tasks(ctx, last)- def _refine_task(self, ctx: RunContext, group: TaskGroup, last: RoundRecord, index: int, *, parallel: bool) -> GenerationTask:- files = group.files if parallel else (group.files or expected_files(ctx))+ def _refine_task(+ self, ctx: RunContext, group: TaskGroup, last: RoundRecord, index: int, *, parallel: bool+ ) -> GenerationTask:+ # scope is real whenever the judge's targets resolved to files — parallel or not.+ # A group whose targets did not resolve (target "overall") keeps the whole tree.+ scoped = parallel or bool(group.files)+ files = group.files if scoped else expected_files(ctx)lines = compact_instructions(group.tasks, max_lines=ctx.policy.max_instructions_per_task)- prompt = render(self.refine_template, **base_prompt_context(- ctx, round_index=index, tasks=lines, targets=group.targets, files=files,- edit_only_these=parallel, judge_summary=judge_digest(last), measurement_notes=measurement_vs_plan(last, ctx.plan, ctx.language),- current_files=current_files(ctx, files) if ctx.single_shot else {}))+ prompt = render(+ self.refine_template,+ **base_prompt_context(+ ctx,+ round_index=index,+ tasks=lines,+ targets=group.targets,+ files=files,+ edit_only_these=scoped,+ judge_summary=judge_digest(last),+ measurement_notes=measurement_vs_plan(last, ctx.plan, ctx.language),+ current_files=current_files(ctx, files) if ctx.single_shot else {},+ ),+ )ctx.record_prompt("refine", prompt)- return GenerationTask(label=f"refine_{group.label}" if parallel else "refine", prompt=prompt, system=self.system_prompt(ctx),- files_hint=files, round=index, kind="refine", temperature=0.4, thinking="medium",- images=reference_images(ctx))+ return GenerationTask(+ label=f"refine_{group.label}" if parallel else "refine",+ prompt=prompt,+ system=self.system_prompt(ctx),+ files_hint=files,+ round=index,+ kind="refine",+ temperature=0.4,+ thinking="medium",+ images=reference_images(ctx),+ edit_only=scoped,+ )# ------------------------------------------------------------------ detail round- def detail_tasks(self, ctx: RunContext, last: RoundRecord, index: int) -> tuple[list[GenerationTask], list[str]]:+ def detail_tasks(+ self, ctx: RunContext, last: RoundRecord, index: int+ ) -> tuple[list[GenerationTask], list[str]]:"""One surface-detail round: bevels, seams, fasteners, wear, material variation —with the silhouette, the placement and the part list frozen.@@ -248,7 +364,9 @@ class StaticObjectTrack(BaseTrack):``ctx.extra`` records the round index and the measurement to diff against, whichis what ``ObjectPipeline.gates`` turns into the ``detail_drift`` gate."""- lines = detail_instructions(last, ctx.plan, max_lines=ctx.policy.max_instructions_per_task + 2)+ lines = detail_instructions(+ last, ctx.plan, max_lines=ctx.policy.max_instructions_per_task + 2+ )if not lines:return [], []ctx.extra["detail_round"] = index@@ -258,35 +376,74 @@ class StaticObjectTrack(BaseTrack):if scopes:for scope in scopes:files = list(scope.files)- prompt = render(self.detail_template, **scope_context(- ctx, scope, round_index=index, tasks=lines, files=files,- judge_summary=judge_digest(last),- current_files=current_files(ctx, files) if ctx.single_shot else {}))- tasks.append(GenerationTask(- label=f"detail_{scope.label}", prompt=prompt, system=self.detail_system_prompt(ctx),- files_hint=files, round=index, kind=DETAIL_KIND, temperature=0.6, thinking="high"))+ prompt = render(+ self.detail_template,+ **scope_context(+ ctx,+ scope,+ round_index=index,+ tasks=lines,+ files=files,+ judge_summary=judge_digest(last),+ current_files=current_files(ctx, files) if ctx.single_shot else {},+ ),+ )+ tasks.append(+ GenerationTask(+ label=f"detail_{scope.label}",+ prompt=prompt,+ system=self.detail_system_prompt(ctx),+ files_hint=files,+ round=index,+ kind=DETAIL_KIND,+ temperature=0.6,+ thinking="high",+ )+ )else:files = expected_files(ctx)- prompt = render(self.detail_template, **base_prompt_context(- ctx, round_index=index, tasks=lines, files=files, judge_summary=judge_digest(last),- current_files=current_files(ctx, files) if ctx.single_shot else {}))- tasks.append(GenerationTask(- label="detail", prompt=prompt, system=self.detail_system_prompt(ctx), files_hint=files,- round=index, kind=DETAIL_KIND, temperature=0.6, thinking="high"))+ prompt = render(+ self.detail_template,+ **base_prompt_context(+ ctx,+ round_index=index,+ tasks=lines,+ files=files,+ judge_summary=judge_digest(last),+ current_files=current_files(ctx, files) if ctx.single_shot else {},+ ),+ )+ tasks.append(+ GenerationTask(+ label="detail",+ prompt=prompt,+ system=self.detail_system_prompt(ctx),+ files_hint=files,+ round=index,+ kind=DETAIL_KIND,+ temperature=0.6,+ thinking="high",+ )+ )ctx.record_prompt("detail", tasks[0].prompt)- ctx.events.emit("detail.planned", round=index, n_tasks=len(tasks), n_lines=len(lines),- tol_mm=round(ctx.policy.detail_bbox_tol_m * 1000, 1))+ ctx.events.emit(+ "detail.planned",+ round=index,+ n_tasks=len(tasks),+ n_lines=len(lines),+ tol_mm=round(ctx.policy.detail_bbox_tol_m * 1000, 1),+ )return tasks, linesdef detail_system_prompt(self, ctx: RunContext) -> str:- return (f"You are an expert {ctx.language.value} 3D modeller adding SURFACE DETAIL to a model whose structure "- f"is already accepted. You may not move, resize, rename, add or remove a part — a deterministic gate "- f"compares every part's bounding box against the previous round and fails the round if one moved. "- f"Everything you add lives inside or on an existing part's surface.")-+ return (+ f"You are an expert {ctx.language.value} 3D modeller adding SURFACE DETAIL to a model whose structure "+ f"is already accepted. You may not move, resize, rename, add or remove a part — a deterministic gate "+ f"compares every part's bounding box against the previous round and fails the round if one moved. "+ f"Everything you add lives inside or on an existing part's surface."+ )# ----------------------------------------------------------------------------- helpersdef refine_task_lines(tasks: Sequence[RefineTask]) -> list[str]:return [t.line() for t in tasks]-diff --git a/harness/tests/agents/test_edit_scope.py b/harness/tests/agents/test_edit_scope.pynew file mode 100644index 00000000..32a24a0c--- /dev/null+++ b/harness/tests/agents/test_edit_scope.py@@ -0,0 +1,62 @@+"""``edit_only``: a refine session may not overwrite part files the round did not name.++Measured 2026-08-25 over 128 judged refine rounds on static objects: the rounds that+REGRESSED had rewritten a median 6 of 9 part files, the rounds that improved 4 of 8, and+the regressions' worst-dropping criterion was structure_plausibility with zero gate errors+— working geometry the task never mentioned was replaced, and nothing deterministic saw+it. The prompt already said "keep everything else as it is"; only the tool can hold it.+"""++from __future__ import annotations++import pytest++from codeverse.agents.api_tools import FileTools, PathDenied+from codeverse.workspace import Workspace+++def _ws(tmp_path):+ ws = Workspace(tmp_path / "run")+ ws.create()+ (ws.root / "src" / "parts").mkdir(parents=True, exist_ok=True)+ (ws.root / "src" / "model.py").write_text("# entry\n")+ (ws.root / "src" / "parts" / "seat.py").write_text("# seat\n")+ (ws.root / "src" / "parts" / "leg.py").write_text("# leg\n")+ return ws+++def test_a_scoped_session_cannot_overwrite_a_neighbouring_part(tmp_path):+ ws = _ws(tmp_path)+ ft = FileTools(ws, ["src", "public"], edit_only=["src/parts/seat.py"], always_writable=["src/model.py"])+ assert not ft.write_file("src/parts/seat.py", "# new seat\n").is_error, "the named file is editable"+ with pytest.raises(PathDenied) as ei: # the agent loop turns PathDenied into a tool error+ ft.write_file("src/parts/leg.py", "# rewritten leg\n")+ assert "leg.py" in str(ei.value) and "seat.py" in str(ei.value), "the refusal names the file and the allowed list"+ assert (ws.root / "src" / "parts" / "leg.py").read_text() == "# leg\n", "and nothing was written"+ assert ft.scope_denials == ["src/parts/leg.py"], "denials are counted so the rate can be measured"+++def test_new_files_and_the_entry_file_stay_writable(tmp_path):+ """Adding a part means a new file AND an import line in the entry: both must work."""+ ws = _ws(tmp_path)+ ft = FileTools(ws, ["src", "public"], edit_only=["src/parts/seat.py"], always_writable=["src/model.py"])+ assert not ft.write_file("src/parts/armrest.py", "# new part\n").is_error+ assert not ft.write_file("src/model.py", "# entry + import\n").is_error+ assert ft.scope_denials == []+++def test_no_scope_means_the_old_behaviour(tmp_path):+ """Baseline sessions and unscoped refines (target 'overall') keep the whole tree."""+ ws = _ws(tmp_path)+ ft = FileTools(ws, ["src", "public"])+ assert ft.edit_only is None+ assert not ft.write_file("src/parts/leg.py", "# fine\n").is_error+++def test_scope_never_widens_the_write_roots(tmp_path):+ """edit_only narrows; it must not let a listed path escape src/ or public/."""+ ws = _ws(tmp_path)+ (ws.root / "artifacts").mkdir(exist_ok=True)+ ft = FileTools(ws, ["src", "public"], edit_only=["artifacts/x.txt"])+ with pytest.raises(PathDenied, match="only allowed under"):+ ft.write_file("artifacts/x.txt", "nope")