Official Codebase of 3DCodeVerse
Python
agents: a session never outlives the run's hard clock — AgentJob.hard_deadline_s, and codex's MCP keeps the caller's PYTHONPATH
gaoypenge55fdac9e8c0
diff --git a/eval/bench/_bare_agent.py b/eval/bench/_bare_agent.pyindex ad9d2025..69046b40 100644--- a/eval/bench/_bare_agent.py+++ b/eval/bench/_bare_agent.py@@ -14,6 +14,7 @@ The delivered file(s) are then scored by the SAME fixed evaluator as every otherfrom __future__ import annotationsimport shutil+import timefrom pathlib import Pathfrom bench._oneshot import files_for@@ -79,6 +80,7 @@ def run_bare_agent(spec: Spec, target: str, cell: Path, eval_ws: Workspace, *, m(ws.root / "tmp").mkdir(exist_ok=True)job = AgentJob(workspace=str(ws.root), prompt=bare_agent_prompt(spec, minutes), label="bare",timeout_s=int(minutes * 60), spatial_tools=False, write_roots=["src", "tmp"],+ hard_deadline_s=time.monotonic() + minutes * 60,kind="baseline", language=spec.language.value, track=spec.track.value,env={"NODE_PATH": str(node_modules_dir())})result = get_coding_agent(target).run(job)diff --git a/eval/tests/test_bare_agent.py b/eval/tests/test_bare_agent.pyindex 8811feff..82faf71c 100644--- a/eval/tests/test_bare_agent.py+++ b/eval/tests/test_bare_agent.py@@ -59,12 +59,16 @@ class _FakeAgent:def test_run_copies_the_deliverable_and_resumes(tmp_path, monkeypatch):+ import time+agent = _FakeAgent()monkeypatch.setattr("bench._bare_agent.get_coding_agent", lambda target: agent)eval_ws = Workspace(tmp_path / "eval").create()+ started = time.monotonic()r = run_bare_agent(_spec(), "gemini-cli:gemini-3.7-flash", tmp_path, eval_ws, minutes=10)assert r.ok and (eval_ws.root / "src" / "model.py").read_text() == "import bpy\n"job = agent.jobs[0]assert job.spatial_tools is False and job.timeout_s == 600 and job.write_roots == ["src", "tmp"]+ assert started + 600 <= job.hard_deadline_s <= time.monotonic() + 600run_bare_agent(_spec(), "gemini-cli:gemini-3.7-flash", tmp_path, eval_ws, minutes=10)assert len(agent.jobs) == 1 # a finished session is not re-rundiff --git a/harness/codeverse3d/agents/cli_common.py b/harness/codeverse3d/agents/cli_common.pyindex 9d1657cd..9473b4bb 100644--- a/harness/codeverse3d/agents/cli_common.py+++ b/harness/codeverse3d/agents/cli_common.py@@ -575,8 +575,15 @@ def invoke(``invoke`` line records ``attempt`` and the prompt's size, plus ``invoke_extra`` (gemini-cliadds ``model`` and ``key_tail``)."""+ soft = float(s.job.timeout_s if soft_timeout_s is None else soft_timeout_s)+ hard = soft + 300.0+ if s.job.hard_deadline_s is not None:+ # This runs AFTER begin_session's workspace lock and on every vendor retry.+ # A queued job must not regain the window it had before waiting for a peer.+ hard = min(hard, max(0.0, s.job.hard_deadline_s - time.monotonic()))+ soft = min(soft, hard)s.traj.append("invoke", argv=list(argv), attempt=attempt, stdin_bytes=len(prompt.encode("utf-8")),- **invoke_extra)+ soft_timeout_s=soft, hard_timeout_s=hard, started=hard > 0, **invoke_extra)def on_line(stream: str, line: str) -> None:s.traj.append("line", stream=stream, text=line[:4000])@@ -584,16 +591,15 @@ def invoke(if observer is not None:observer(line)- # A streaming session must not outlive its window by half of it again: the watchdog's- # default hard kill is max(1.5x soft, soft+600), and chair_bl (loop_w1, 2026-08-28)- # streamed straight past a 16-minute window for 37 minutes. Five minutes of grace is- # what the budget salvage gets; the session gets the same.- soft = float(s.job.timeout_s if soft_timeout_s is None else soft_timeout_s)- proc = run_with_watchdog(- argv, cwd=s.ws.root, env=env, soft_timeout_s=soft, hard_timeout_s=soft + 300.0,- idle_grace_s=IDLE_GRACE_S, poll_s=POLL_S,- on_line=on_line, stdin=prompt, activity_dirs=[s.ws.src, s.ws.public],- )+ if hard <= 0:+ proc = CompletedProc(rc=-9, stdout="", stderr="Run deadline expired before CLI launch.\n",+ duration_s=0.0, timed_out=True, killed_reason="hard_timeout")+ else:+ proc = run_with_watchdog(+ argv, cwd=s.ws.root, env=env, soft_timeout_s=soft, hard_timeout_s=hard,+ idle_grace_s=IDLE_GRACE_S, poll_s=POLL_S,+ on_line=on_line, stdin=prompt, activity_dirs=[s.ws.src, s.ws.public],+ )suffix = "" if attempt == 1 else f".{attempt}"out = Path(stdout_name)s.traj.write_text(f"{out.stem}{suffix}{out.suffix}", proc.stdout)diff --git a/harness/codeverse3d/agents/materialize.py b/harness/codeverse3d/agents/materialize.pyindex 2fb7fa78..ee15c915 100644--- a/harness/codeverse3d/agents/materialize.py+++ b/harness/codeverse3d/agents/materialize.py@@ -179,6 +179,10 @@ def codex_mcp_overrides(mcp_command: list[str]) -> list[str]:return ["-c", f"mcp_servers.{MCP_SERVER_NAME}.command={json.dumps(mcp_command[0])}","-c", f"mcp_servers.{MCP_SERVER_NAME}.args={_toml_str_list(mcp_command[1:])}",+ # Codex filters the environment of stdio MCP subprocesses. Preserve the+ # caller's explicit engine/runtime selection (e.g. a frozen benchmark+ # checkout) instead of silently importing an unrelated editable install.+ "-c", f"mcp_servers.{MCP_SERVER_NAME}.env_vars={_toml_str_list(['PYTHONPATH', 'C3D_RUNTIME_JS'])}","-c", f"mcp_servers.{MCP_SERVER_NAME}.tool_timeout_sec={MCP_TOOL_TIMEOUT_MS // 1000}","-c", f"mcp_servers.{MCP_SERVER_NAME}.startup_timeout_sec=60","-c", f"mcp_servers.{MCP_SERVER_NAME}.default_tools_approval_mode={json.dumps(CODEX_MCP_APPROVAL_MODE)}",diff --git a/harness/codeverse3d/contracts/agent.py b/harness/codeverse3d/contracts/agent.pyindex 228e6ef8..3fdc79e0 100644--- a/harness/codeverse3d/contracts/agent.py+++ b/harness/codeverse3d/contracts/agent.py@@ -26,6 +26,12 @@ class AgentJob(BaseModel):system_append: str = ""label: str = ""timeout_s: int = 1800+ hard_deadline_s: float | None = Field(+ default=None, ge=0, allow_inf_nan=False,+ description="absolute time.monotonic() deadline on this host, derived from the run's "+ "remaining hard clock before queuing. Shared by retries; recomputed on resume. "+ "None preserves the standalone CLI's session grace",+ )#: consumed only by claude-code (``--max-turns``); gemini-cli / codex / agy have no#: turn flag and run unbounded except by ``timeout_s`` and the run's wall clockmax_turns: int = 60diff --git a/harness/codeverse3d/tracks/generation.py b/harness/codeverse3d/tracks/generation.pyindex f4823f23..13a24a70 100644--- a/harness/codeverse3d/tracks/generation.py+++ b/harness/codeverse3d/tracks/generation.py@@ -35,6 +35,7 @@ from __future__ import annotationsimport loggingimport reimport shutil+import timefrom collections.abc import Callable, Collectionfrom pathlib import Path, PurePosixPathfrom typing import Any@@ -522,6 +523,11 @@ def run_agent_task(# window of its own (repair) is still bounded by the soft share, so a failing# baseline cannot eat the refine rounds' half. (Both found by review 2026-08-29.)timeout = _deadline_preflight(budget, timeout, soft=task.timeout_s is None)+ # Sessions sharing a workspace wait for a lock. An absolute deadline keeps that+ # wait, retry attempts and the CLI's activity grace inside the run's hard clock.+ hard_deadline = None+ if budget is not None and hasattr(budget, "timeout_s"):+ hard_deadline = time.monotonic() + budget.timeout_s(float("inf"), floor_s=0, soft=False)turns_cap = agent_max_turns() # 0 = leave AgentJob's own default# typed job context honoured by every CodingAgent: round → trajectory dir + ToolContext,# language/track → spatial tool filtering, files_hint → the edit_only scope.@@ -533,6 +539,7 @@ def run_agent_task(system_append=task.system,label=task.label,timeout_s=timeout,+ hard_deadline_s=hard_deadline,spatial_tools=True,write_roots=task.write_roots,round=task.round,@@ -624,8 +631,8 @@ class _SessionAcc:Each session is a ledger row the moment it returns (label ``<task>``/``<task>.a2`` forthe retry, ``<task>.wrapup`` for the landing session — ``cost.instrument.MeteredAgent``),so a crash in a later session can never erase what an earlier one already spent — the- ``.a2`` hole of docs/COST.md §6. The run's clock is checked after each session that- did any work, as the guard's charge did before money left it."""+ ``.a2`` hole of docs/COST.md §6. The run's clock is checked before and after+ every session, including sessions whose vendor returned no usage."""def __init__(self, *, task: GenerationTask, budget: Any | None):self.task = task@@ -648,6 +655,8 @@ class _SessionAcc:".wrapup" if wrapup else (f".a{self.sessions}" if self.sessions > 1 else ""))try:+ if self.budget is not None:+ self.budget.check()res: AgentResult = agent.run(job)except Exception as e: # noqa: BLE001 — a budget stop still propagates (see below)self.sessions -= 1@@ -660,7 +669,7 @@ class _SessionAcc:# the count as the BACKEND reports it (0 for gemini-cli, which exposes none): a size# signal for the generate.turn_cap event, not what the cap is enforced againstself.turns += res.turns- if self.budget is not None and (res.usage.cost_usd or res.usage.input_tokens or res.usage.output_tokens):+ if self.budget is not None:self.budget.check()return resdiff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 8908bb31..82d0a02d 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -208,6 +208,11 @@ from codeverse3d.agents.cli_common import is_transient_failure, is_quota_failure# its session) and provider_wait(failures=[(t, backoff_s)], end, progress=[t] | None) -> seconds````AgentJob` carries typed job context: `round`, `kind`, `language`, `track`,+`hard_deadline_s` (optional absolute `time.monotonic()` deadline on this host:+generation derives it from the remaining hard run clock before queueing; every CLI+attempt clips its watchdog after acquiring the workspace lock, including retries.+An expired job never launches a CLI. Recomputed on resume; `None` keeps standalone+session grace. Process termination and final packaging can finish after the deadline),`mcp_command` (override), `files_hint` (workspace-relative files/dirs the task isexpected to touch — used to attribute `files_changed`; harness-owned paths are dropped;sessions on one workspace are serialised, so there is no sibling filter),diff --git a/harness/tests/agents/test_agent_job_wiring.py b/harness/tests/agents/test_agent_job_wiring.pyindex 576f55a0..058958de 100644--- a/harness/tests/agents/test_agent_job_wiring.py+++ b/harness/tests/agents/test_agent_job_wiring.py@@ -3,10 +3,14 @@ prompt section, a hard-clock session window, the backend's turn count."""from __future__ import annotations+import time++import pytest+from codeverse3d.contracts.agent import AgentJob, AgentResultfrom codeverse3d.contracts.chat import ImagePartfrom codeverse3d.contracts.common import Budget, Usage-from codeverse3d.orchestrator import BudgetGuard+from codeverse3d.orchestrator import BudgetExceeded, BudgetGuardfrom codeverse3d.tracks.generation import GenerationTask, run_agent_taskfrom codeverse3d.workspace import Workspace@@ -55,3 +59,44 @@ def test_session_window_is_clipped_to_the_hard_clock_not_the_soft_share(tmp_ws:run_agent_task(tmp_ws, agent=agent, task=GenerationTask(label="refine", prompt="p", timeout_s=900), budget=guard)assert agent.jobs[0].timeout_s == 900++def test_run_deadline_overrides_the_session_timeout_floor(tmp_ws: Workspace):+ guard = BudgetGuard(Budget(max_minutes=1))+ guard.start_time -= 50+ agent = StubAgent()+ start = time.monotonic()+ run_agent_task(tmp_ws, agent=agent, task=GenerationTask(label="refine", prompt="p"), budget=guard)+ job = agent.jobs[0]+ assert job.timeout_s == 120 # the existing soft session floor+ assert start < job.hard_deadline_s <= start + 10+++def test_silent_retry_keeps_the_original_absolute_deadline(tmp_ws: Workspace):+ class BailOnce(StubAgent):+ def run(self, job):+ if not self.jobs:+ self.jobs.append(job)+ return AgentResult(ok=False, exit_reason="completed")+ return super().run(job)++ agent = BailOnce()+ run_agent_task(tmp_ws, agent=agent, task=GenerationTask(label="baseline", prompt="p"),+ budget=BudgetGuard(Budget(max_minutes=1)))+ assert len(agent.jobs) == 2+ assert agent.jobs[0].hard_deadline_s is not None+ assert agent.jobs[0].hard_deadline_s == agent.jobs[1].hard_deadline_s+++def test_empty_usage_cannot_bypass_the_clock_and_start_a_retry(tmp_ws: Workspace):+ guard = BudgetGuard(Budget(max_minutes=1))++ class EmptyOverrun(StubAgent):+ def run(self, job):+ self.jobs.append(job)+ guard.start_time -= 61+ return AgentResult(ok=False, exit_reason="completed")++ agent = EmptyOverrun()+ with pytest.raises(BudgetExceeded):+ run_agent_task(tmp_ws, agent=agent, task=GenerationTask(label="baseline", prompt="p"), budget=guard)+ assert len(agent.jobs) == 1diff --git a/harness/tests/agents/test_cli_common.py b/harness/tests/agents/test_cli_common.pyindex d667caeb..0cba0e1f 100644--- a/harness/tests/agents/test_cli_common.py+++ b/harness/tests/agents/test_cli_common.py@@ -4,7 +4,12 @@ from __future__ import annotationsimport jsonimport os+import sys+import time+import pytest++from codeverse3d.agents import cli_commonfrom codeverse3d.agents.cli_common import (begin_session,clean_env,@@ -89,6 +94,56 @@ def test_one_failure_vocabulary():assert is_rate_limited("status 429") and is_rate_limited("RESOURCE_EXHAUSTED") and not is_rate_limited("503")+def test_queued_invocation_and_retry_share_the_run_deadline(tmp_ws: Workspace, monkeypatch):+ clock = [100.0]+ windows = []++ def watchdog(argv, **kwargs):+ windows.append((kwargs["soft_timeout_s"], kwargs["hard_timeout_s"]))+ return cli_common.CompletedProc(rc=0, stdout="", stderr="", duration_s=0)++ s = begin_session(AgentJob(workspace=str(tmp_ws.root), prompt="p", timeout_s=120,+ hard_deadline_s=110.0), "fake")+ monkeypatch.setattr(cli_common.time, "monotonic", lambda: clock[0])+ monkeypatch.setattr(cli_common, "run_with_watchdog", watchdog)+ clock[0] = 104.0 # waiting for a workspace lock consumed four seconds+ invoke(s, ["unused"], {}, prompt="p")+ clock[0] = 109.0+ invoke(s, ["unused"], {}, prompt="p", attempt=2, soft_timeout_s=90)+ assert windows == [(6.0, 6.0), (1.0, 1.0)]+ clock[0] = 111.0+ expired = invoke(s, ["unused"], {}, prompt="p", attempt=3)+ assert len(windows) == 2 and expired.timed_out and expired.duration_s == 0+ assert "before CLI launch" in (s.traj.dir / "stderr.3.log").read_text()+ assert [r["started"] for r in s.traj.read_transcript() if r["kind"] == "invoke"] == [True, True, False]+++def test_standalone_invocation_keeps_its_activity_grace(tmp_ws: Workspace, monkeypatch):+ windows = []++ def watchdog(argv, **kwargs):+ windows.append((kwargs["soft_timeout_s"], kwargs["hard_timeout_s"]))+ return cli_common.CompletedProc(rc=0, stdout="", stderr="", duration_s=0)++ monkeypatch.setattr(cli_common, "run_with_watchdog", watchdog)+ s = begin_session(AgentJob(workspace=str(tmp_ws.root), prompt="p", timeout_s=120), "fake")+ invoke(s, ["unused"], {}, prompt="p")+ assert windows == [(120.0, 420.0)]++[email protected](20, method="thread")+def test_invoke_stops_an_active_cli_at_the_run_deadline(tmp_ws: Workspace, monkeypatch):+ s = begin_session(AgentJob(workspace=str(tmp_ws.root), prompt="p", timeout_s=120,+ hard_deadline_s=time.monotonic() + 1), "fake")+ monkeypatch.setattr(cli_common, "POLL_S", 0.05)+ code = "import time\nwhile True:\n print('still active', flush=True); time.sleep(0.05)"+ started = time.monotonic()+ proc = invoke(s, [sys.executable, "-c", code], dict(os.environ), prompt="p")+ assert proc.timed_out and proc.killed_reason == "hard_timeout"+ assert "still active" in proc.stdout+ assert time.monotonic() - started < 10++def test_provider_wait_counts_each_burst_from_the_request_that_failed():# progress at 0 and 100; a burst of three failures, back-off announced, then progress againassert provider_wait([(10.0, 5.0), (20.0, 10.0), (35.0, 20.0)], end=500.0, progress=[0.0, 100.0]) == 55.0diff --git a/harness/tests/agents/test_materialize.py b/harness/tests/agents/test_materialize.pyindex 30328781..48b6fc8f 100644--- a/harness/tests/agents/test_materialize.py+++ b/harness/tests/agents/test_materialize.py@@ -3,9 +3,13 @@from __future__ import annotationsimport json+import os+import subprocess+import sys+import tomllibfrom codeverse3d.agents.cli_common import default_mcp_command-from codeverse3d.agents.materialize import materialize_workspace+from codeverse3d.agents.materialize import codex_mcp_overrides, materialize_workspacefrom codeverse3d.workspace import WorkspaceCONTRACT = "## blender contract\nWrite pure bpy into src/model.py."@@ -90,3 +94,25 @@ def test_kind_specific_tool_hint_and_spatial_disabled_documents_absence(tmp_ws:assert "codeverse3d.cli.main tools" in (tmp_ws.root / "AGENTS.md").read_text()_mat(tmp_ws, spatial=False)assert "No spatial tools are available" in (tmp_ws.root / "AGENTS.md").read_text()+++def test_codex_mcp_preserves_explicit_engine_selection(tmp_path, monkeypatch):+ """A caller-selected module must remain importable after Codex filters MCP env."""+ selected = tmp_path / "frozen engine"+ selected.mkdir()+ (selected / "c3d_selected_probe.py").write_text("IDENTITY = 'frozen-engine'\n")+ runtime = str(selected / "runtime_js")+ monkeypatch.setenv("PYTHONPATH", str(selected))+ monkeypatch.setenv("C3D_RUNTIME_JS", runtime)+ monkeypatch.setenv("UNRELATED_SERVICE_API_KEY", "test-only-sentinel")+ overrides = codex_mcp_overrides([sys.executable, "-m", "unused"])+ config = tomllib.loads("\n".join(overrides[1::2]))["mcp_servers"]["3dcode"]+ # Model the documented MCP allowlist and exercise actual Python resolution.+ forwarded = {name: os.environ[name] for name in config["env_vars"] if name in os.environ}+ run = subprocess.run(+ [sys.executable, "-c", "import c3d_selected_probe, os; "+ "print(c3d_selected_probe.IDENTITY); print(os.environ.get('C3D_RUNTIME_JS')); "+ "print('UNRELATED_SERVICE_API_KEY' in os.environ)"],+ env=forwarded, cwd=tmp_path, capture_output=True, text=True, check=True,+ )+ assert run.stdout.splitlines() == ["frozen-engine", runtime, "False"]diff --git a/harness/tests/prompts/manifest.py b/harness/tests/prompts/manifest.pyindex 45ca4be0..ca005554 100644--- a/harness/tests/prompts/manifest.py+++ b/harness/tests/prompts/manifest.py@@ -104,7 +104,7 @@ BRIEF = {"object_name": "DiningChair", "reference": "a Danish oak dining chair","mechanism": "the legs carry the seat", "visible_from_outside": ["seat", "legs", "backrest"],"signature_features": ["tapered legs", "curved backrest"], "materials": ["seat: oiled oak"]}CONTEXT_FILES = ("AGENTS.md", "GEMINI.md", "CLAUDE.md", ".3dcode/cookbook.md", ".gemini/settings.json", ".geminiignore", ".aiexclude")-VOLATILE = frozenset({"duration_ms", "duration_s", "latency_ms", "max_wait_s", "timeout_s", "workspace", "data_b64"})+VOLATILE = frozenset({"duration_ms", "duration_s", "latency_ms", "max_wait_s", "timeout_s", "hard_deadline_s", "workspace", "data_b64"})SHADER = ("void mainImage(out vec4 fragColor, in vec2 fragCoord) {{\n vec2 uv = fragCoord / u_resolution.xy;\n"" // {tag}\n fragColor = vec4(uv, 0.5 + 0.5 * sin(u_time), 1.0);\n}}\n")PROGRAM = ("import moderngl # {tag}\n\n\ndef setup(ctx, width, height):\n return {{}}\n\n\n"