Skip to content

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.py
index 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, chat
job = 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 = None
if 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 here
self.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 = 0
self.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"],
+ )
break
resp = self._generate(turn)
if resp is None:
@@ -147,9 +161,16 @@ class _Loop:
break
text = resp.text
self.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:
break
self._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}"],
+ )
break
if 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.0
for attempt in range(MODEL_RETRIES):
try:
@@ -183,7 +221,13 @@ class _Loop:
return resp
except Exception as e: # ModelError or provider glitch
retryable = 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.py
index a628894b..4c6fc95c 100644
--- a/harness/codeverse/agents/api_tools.py
+++ b/harness/codeverse/agents/api_tools.py
@@ -16,6 +16,7 @@ import fnmatch
import json
import os
import shlex
+from collections.abc import Collection
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
@@ -28,16 +29,47 @@ from codeverse.workspace import Workspace
READ_CAP_CHARS = 60_000
SHELL_OUT_CAP = 6_000
SHELL_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 = ws
self.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_shell
self.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 specs
def names(self) -> set[str]:
@@ -97,8 +197,13 @@ class FileTools:
# ------------------------------------------------------------------ dispatch
def 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 name
p = 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():
continue
rel = 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]
+ ):
continue
if 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.py
index 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.3
thinking: str = "low"
allow_shell: bool = True
@@ -39,12 +41,18 @@ class AgentJob(BaseModel):
timeout_s: int = 1800
max_turns: int = 60
allow_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 context
round: 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")
@classmethod
diff --git a/harness/codeverse/prompts/tracks/refine_object.j2 b/harness/codeverse/prompts/tracks/refine_object.j2
index 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 keep
Targets: {{ 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.py
index 0af05ab3..c0f63ead 100644
--- a/harness/codeverse/tracks/generation.py
+++ b/harness/codeverse/tracks/generation.py
@@ -116,8 +116,12 @@ class GenerationTask(BaseModel):
label: str
prompt: 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 = 0
kind: str = "generate"
images: list[ImagePart] = Field(default_factory=list)
@@ -125,13 +129,24 @@ class GenerationTask(BaseModel):
thinking: str = "medium"
max_output_tokens: int = 32000
timeout_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 it
if 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 only
pass
# 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 res
changes = 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 res
changes = 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 = False
self.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) never
take the task down: a crash there leaves the earlier, already charged
session as the result instead of discarding money that was really spent."""
self.sessions += 1
self.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) -> li
from codeverse.agents.cli_common import attribute_changes
except ImportError: # pragma: no cover — agents package always ships with tracks
return 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_factory
model = 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_factory
agent = 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.py
index 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 None
if 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 frame
if 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 judge
if 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-fatal
log.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 None
def plan_summary(self, ctx: RunContext) -> str:
plan = ctx.plan
if 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 scoped
files = 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 baseline
def 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"] = got
return 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 tasks
def 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, which
is 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, lines
def 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."
+ )
# ----------------------------------------------------------------------------- helpers
def 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.py
new file mode 100644
index 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")