Skip to content

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.py
index 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 other
from __future__ import annotations
import shutil
+import time
from pathlib import Path
from 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.py
index 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() + 600
run_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-run
diff --git a/harness/codeverse3d/agents/cli_common.py b/harness/codeverse3d/agents/cli_common.py
index 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-cli
adds ``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.py
index 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.py
index 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 clock
max_turns: int = 60
diff --git a/harness/codeverse3d/tracks/generation.py b/harness/codeverse3d/tracks/generation.py
index f4823f23..13a24a70 100644
--- a/harness/codeverse3d/tracks/generation.py
+++ b/harness/codeverse3d/tracks/generation.py
@@ -35,6 +35,7 @@ from __future__ import annotations
import logging
import re
import shutil
+import time
from collections.abc import Callable, Collection
from pathlib import Path, PurePosixPath
from 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`` for
the 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 against
self.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 res
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 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 is
expected 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.py
index 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, AgentResult
from codeverse3d.contracts.chat import ImagePart
from codeverse3d.contracts.common import Budget, Usage
-from codeverse3d.orchestrator import BudgetGuard
+from codeverse3d.orchestrator import BudgetExceeded, BudgetGuard
from codeverse3d.tracks.generation import GenerationTask, run_agent_task
from 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) == 1
diff --git a/harness/tests/agents/test_cli_common.py b/harness/tests/agents/test_cli_common.py
index 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 annotations
import json
import os
+import sys
+import time
+import pytest
+
+from codeverse3d.agents import cli_common
from 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 again
assert provider_wait([(10.0, 5.0), (20.0, 10.0), (35.0, 20.0)], end=500.0, progress=[0.0, 100.0]) == 55.0
diff --git a/harness/tests/agents/test_materialize.py b/harness/tests/agents/test_materialize.py
index 30328781..48b6fc8f 100644
--- a/harness/tests/agents/test_materialize.py
+++ b/harness/tests/agents/test_materialize.py
@@ -3,9 +3,13 @@
from __future__ import annotations
import json
+import os
+import subprocess
+import sys
+import tomllib
from codeverse3d.agents.cli_common import default_mcp_command
-from codeverse3d.agents.materialize import materialize_workspace
+from codeverse3d.agents.materialize import codex_mcp_overrides, materialize_workspace
from codeverse3d.workspace import Workspace
CONTRACT = "## 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.py
index 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"