Skip to content

Official Codebase of 3DCodeVerse

Python

docs(code): four module docstrings say what the module holds now

gaoypeng2bc542640f3f
diff --git a/harness/codeverse3d/agents/cli_common.py b/harness/codeverse3d/agents/cli_common.py
index c4b87750..9d1657cd 100644
--- a/harness/codeverse3d/agents/cli_common.py
+++ b/harness/codeverse3d/agents/cli_common.py
@@ -1,8 +1,8 @@
-"""Trajectory folder helper: prompt.md, transcript.jsonl, stdout/stderr, result.json.
-
-Every CodingAgent backend writes its session here
-(``ws.trajectory_dir(label, round)``) so the flywheel and ``3dcode status`` can
-read one uniform layout regardless of backend.
+"""What every vendor-CLI backend (``agents/backends.py``) shares: the trajectory folder
+(prompt.md, transcript.jsonl, stdout/stderr, result.json under
+``ws.trajectory_dir(label, round)``, one layout whatever the backend), the watchdog'd
+session process, the hardened environment, the session's write scope and locks, failure
+classification, and the tool-call trace. (``cli/`` is the harness's own ``3dcode`` CLI.)
"""
from __future__ import annotations
diff --git a/harness/codeverse3d/languages/_common.py b/harness/codeverse3d/languages/_common.py
index 70e71c28..f578d08b 100644
--- a/harness/codeverse3d/languages/_common.py
+++ b/harness/codeverse3d/languages/_common.py
@@ -1,6 +1,7 @@
-"""Shared helpers for python-language runtimes (blender, cadquery, urdf).
+"""Shared helpers for the language runtimes — the wrapper build of the python ones
+(blender, cadquery, urdf), and the finding locations and typed failure names every lint uses.
-Runtimes execute a *wrapper script* in a subprocess (Blender's python or the
+The python runtimes execute a *wrapper script* in a subprocess (Blender's python or the
harness python). The wrapper writes ``artifacts/build.json`` (+ ``census.json``)
and the runtime turns those into a :class:`BuildResult`. This module owns:
diff --git a/harness/codeverse3d/proc.py b/harness/codeverse3d/proc.py
index 6e6ca62d..13e33b78 100644
--- a/harness/codeverse3d/proc.py
+++ b/harness/codeverse3d/proc.py
@@ -1,9 +1,11 @@
-"""Subprocess + atomic-JSON primitives shared across the harness.
+"""Process-level primitives shared across the harness.
One home for the run-a-child-process pattern (own process group, wall-clock
timeout, group kill, bounded captured output — :class:`ManagedProcess` and its
-thin wrapper :func:`run_subprocess`), the tmp+rename JSON write, and the
-tolerant JSON / JSONL readers every "best effort" side-car consumer needs. Peer
+thin wrapper :func:`run_subprocess`), the tmp+rename JSON write, the tolerant
+JSON / JSONL readers every "best effort" side-car consumer needs, the run's event
+stream (:class:`EventLog`, :data:`NULL_EVENTS`), the per-run mutex
+(:func:`exclusive`) and the context-carrying thread fan-out (:func:`fan_out`). Peer
of ``workspace.py``; stdlib-only — imports nothing from ``codeverse3d`` so wrappers,
spatial helpers and agents can all use it without layering back-edges.
diff --git a/harness/codeverse3d/tracks/common.py b/harness/codeverse3d/tracks/common.py
index 24829315..cb0329bf 100644
--- a/harness/codeverse3d/tracks/common.py
+++ b/harness/codeverse3d/tracks/common.py
@@ -1,4 +1,4 @@
-"""Shared track machinery: the run context, the services seam, prompt context.
+"""Shared track machinery: the run context, the services seam, the single-shot path.
``Services`` is the tracks' injection seam: every call into a sibling package
(models, agents, runtimes, spatial tools, judges, record) goes through one