novacode-cli 1.2.0__py3-none-any.whl

novacode_cli/__init__.py

@@ -0,0 +1,29 @@
+"""NOVA CLI - Interactive AI coding assistant."""
+
+import os as _os
+
+# Must run before numpy is imported anywhere in the process. numpy's OpenBLAS
+# pre-allocates a buffer per CPU thread at import: on a 12-thread machine that
+# is ~380 MB of private memory for nothing — Nova's numeric work is small
+# vector searches (skill and code retrieval over a few thousand 256-d rows),
+# where one thread is measurably FASTER (91 us vs 180 us for a 1000-row
+# search) because thread hand-off costs more than the arithmetic. One thread:
+# ~9 MB. It applies to every Nova process — the TUI and each spawned session.
+# setdefault, so an explicit setting in the environment still wins.
+_os.environ.setdefault("OPENBLAS_NUM_THREADS", "1")
+# Other numerical backends also default to machine-wide thread pools. Multiple
+# Nova processes should not each occupy every core; explicit user values win.
+_os.environ.setdefault("OMP_NUM_THREADS", "1")
+_os.environ.setdefault("MKL_NUM_THREADS", "1")
+_os.environ.setdefault("NUMEXPR_NUM_THREADS", "1")
+
+# Must run before langchain_core is imported: it pulls in `transformers` (and
+# therefore torch/numpy/PIL) at module scope for a fallback tokenizer Nova never
+# uses, costing ~160 MB RSS and ~10 s of startup. See novacode_cli._lazy_heavy.
+from novacode_cli import _lazy_heavy as _lazy_heavy
+
+_lazy_heavy.install()
+
+# from novacode_cli.main import cli_main
+
+__all__ = []

novacode_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the CLI as: python -m deepagents.cli."""
+
+from novacode_cli.entrypoint import cli_main
+
+if __name__ == "__main__":
+    cli_main()

novacode_cli/_lazy_heavy.py

@@ -0,0 +1,99 @@
+"""Keep `transformers`/`torch` out of Nova's startup import graph.
+
+``langchain_core.language_models.base`` does, at module scope::
+
+    try:
+        from transformers import GPT2TokenizerFast
+        _HAS_TRANSFORMERS = True
+    except ImportError:
+        _HAS_TRANSFORMERS = False
+
+That import is only ever used for a *fallback* GPT-2 token counter
+(``_get_token_ids_default_method``), but ``transformers`` eagerly pulls in
+``torch``, ``numpy``, ``huggingface_hub`` and ``PIL``. Measured on this project:
+
+    full import of novacode_cli.main   305 MB RSS, ~13 s, 4056 modules
+    with transformers/torch excluded   145 MB RSS, ~2.4 s, 3053 modules
+
+Nova talks to hosted model APIs and takes token counts from the provider
+(``get_num_tokens_from_messages``, with char-based fallbacks at every call
+site), so it never needs the GPT-2 tokenizer. Paying 160 MB of resident memory
+and ~10 s of startup for it caused real problems on memory-constrained machines
+(paging-file exhaustion, failed subprocess spawns).
+
+This installs a meta-path finder that makes ``import transformers`` raise
+``ImportError`` — the exact exception langchain_core already handles — so it
+cleanly takes the ``_HAS_TRANSFORMERS = False`` branch.
+
+Escape hatch: set ``NOVA_ALLOW_TRANSFORMERS=1`` to disable the guard. Anything
+that genuinely needs the library (a local HF model, say) can also call
+:func:`allow_transformers` first.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+#: Top-level packages kept out of the startup graph.
+_BLOCKED = frozenset({"transformers", "torch"})
+
+_ENV_OPT_OUT = "NOVA_ALLOW_TRANSFORMERS"
+
+
+class _HeavyImportGuard:
+    """Meta-path finder that refuses the heavy optional deps.
+
+    Raising ``ImportError`` (rather than returning ``None``) is deliberate: the
+    consumers of these packages all wrap the import in ``try/except
+    ImportError`` and degrade gracefully. Returning ``None`` would just let the
+    real finder load them.
+    """
+
+    def find_spec(self, name: str, path: Any = None, target: Any = None) -> None:  # noqa: ANN401, ARG002
+        if name.split(".")[0] in _BLOCKED:
+            msg = (
+                f"{name!r} is not imported at Nova startup (it costs ~160 MB of "
+                f"resident memory and is only needed for a fallback tokenizer). "
+                f"Set {_ENV_OPT_OUT}=1 if you really need it."
+            )
+            raise ImportError(msg)
+        return None
+
+
+_guard: _HeavyImportGuard | None = None
+
+
+def install() -> bool:
+    """Install the guard. Returns True if it is now active.
+
+    No-ops when the user opted out, or when the packages are already imported
+    (blocking then would be pointless — the memory is already committed).
+    """
+    global _guard
+    if os.environ.get(_ENV_OPT_OUT, "").strip().lower() in ("1", "true", "yes"):
+        return False
+    if _guard is not None:
+        return True
+    if any(mod in sys.modules for mod in _BLOCKED):
+        return False
+    _guard = _HeavyImportGuard()
+    sys.meta_path.insert(0, _guard)
+    return True
+
+
+def allow_transformers() -> None:
+    """Remove the guard so ``transformers``/``torch`` can be imported again."""
+    global _guard
+    if _guard is not None:
+        try:
+            sys.meta_path.remove(_guard)
+        except ValueError:
+            pass
+        _guard = None
+
+
+def is_active() -> bool:
+    """Whether the guard is currently installed."""
+    return _guard is not None

novacode_cli/_version.py

@@ -0,0 +1,3 @@
+"""Version information for NOVA CLI."""
+
+__version__ = "1.2.0"

novacode_cli/agent_stream.py

@@ -0,0 +1,178 @@
+"""UI-agnostic agent streaming.
+
+Thin wrapper around :func:`novacode_cli.core.agent_loop.iterate_agent_events`
+that preserves the public ``run_agent_stream`` API for backward compatibility.
+
+Human-in-the-loop interrupts are surfaced as :class:`~novacode_cli.ui_events.InterruptRequest`
+events carrying an ``asyncio.Future`` that the consumer must resolve with the
+decision; the generator awaits it and resumes the graph.
+
+When the learning loop is enabled, each completed turn is graded out-of-band and
+the verdict is logged — that verdict is the quality signal ``/prompt`` evolution
+(prompt-template A/B testing) and ``verification_log`` feed on. Historically only
+the legacy CLI path (``ui/execution.py`` via ``run_with_verification``) produced
+this signal, so the TUI — which calls ``iterate_agent_events`` through here —
+generated nothing, leaving ``verification_log`` empty and auto prompt-evolution
+starved. The grade runs as a fire-and-forget background task: no retries and no
+UI events, so it never delays or alters the turn.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from novacode_cli import ui_events as ev
+from novacode_cli.core.autonomous_loop import run_with_goal
+from novacode_cli.sessions.lease import lease_holder, lease_session
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Callable
+
+# Hold references to in-flight grade tasks so they aren't GC'd mid-run.
+_verification_tasks: set[asyncio.Task] = set()
+
+
+class _NullAsyncCM:
+    """A no-op async context manager (used when there is no thread to lease)."""
+
+    async def __aenter__(self) -> None:
+        return None
+
+    async def __aexit__(self, *exc: object) -> None:
+        return None
+
+
+def _null_async_cm() -> _NullAsyncCM:
+    return _NullAsyncCM()
+
+
+def _maybe_verifier() -> Any | None:
+    """An ``InlineVerifier`` when the learning loop is enabled, else ``None``.
+
+    Gated behind ``learning_enabled`` (opt-in) because grading adds one
+    out-of-band model call per turn. Best-effort — any setup failure returns
+    ``None`` and the turn runs unverified.
+    """
+    try:
+        from novacode_cli.config.nova_config import NovaConfig
+
+        if not NovaConfig().get_learning_enabled():
+            return None
+        from novacode_cli.hermes.verifier import InlineVerifier
+        from novacode_cli.memory.store import get_durable_store
+
+        return InlineVerifier(get_durable_store(), enabled=True)
+    except Exception:  # noqa: BLE001 — learning is best-effort, never break a turn
+        return None
+
+
+def _spawn_verification_signal(
+    verifier: Any,
+    user_input: str,
+    agent_output: str,
+    file_ops: list,
+    session_state: Any,
+    tool_results: list | None = None,
+) -> None:
+    """Grade the finished turn and log the verdict (verification_log + prompt A/B).
+
+    Fire-and-forget: no retries, no UI events. Skipped for a pure no-op turn
+    (nothing produced to grade).
+    """
+    if verifier is None or (not agent_output and not file_ops):
+        return
+
+    async def _grade() -> None:
+        try:
+            from novacode_cli.core.verification_loop import (
+                _extract_diffs,
+                _extract_test_evidence,
+                _record_prompt_ab_outcome,
+            )
+
+            test_evidence = _extract_test_evidence(tool_results or [])
+            diffs = _extract_diffs(file_ops)
+            verdict = await verifier.grade(
+                user_input,
+                agent_output,
+                file_ops,
+                test_evidence=test_evidence,
+                diffs=diffs,
+            )
+            await verifier.log_outcome(getattr(session_state, "thread_id", ""), verdict, 0)
+            # Feed prompt-evolution (Enhancement 2) its quality signal.
+            await _record_prompt_ab_outcome(passed=verdict.passed)
+        except Exception:  # noqa: BLE001 — a grading failure must never surface
+            pass
+
+    task = asyncio.create_task(_grade())
+    _verification_tasks.add(task)
+    task.add_done_callback(_verification_tasks.discard)
+
+
+async def run_agent_stream(
+    user_input: str,
+    agent,
+    assistant_id: str | None,
+    session_state,
+    *,
+    backend=None,
+    image_tracker=None,
+    seen_message_ids: set[str] | None = None,
+    skip_file_mentions: bool = False,
+    can_continue: Callable[[], bool] | None = None,
+) -> AsyncIterator[Any]:
+    """Run the agent and yield UI events.
+
+    Delegates to :func:`~novacode_cli.core.agent_loop.iterate_agent_events` (or
+    :func:`~novacode_cli.core.autonomous_loop.run_with_goal` when a goal is
+    active, so goal mode works from the TUI). Yields instances from
+    :mod:`novacode_cli.ui_events`. Terminates with a
+    :class:`~novacode_cli.ui_events.Done`, :class:`~novacode_cli.ui_events.Cancelled`,
+    or :class:`~novacode_cli.ui_events.Error` event. When learning is enabled,
+    grades the completed turn out-of-band (see module docstring).
+
+    The turn runs under a best-effort cross-process session lease (never blocks;
+    proceeds unleased on conflict).
+    """
+    verifier = _maybe_verifier()
+    texts: list[str] = []
+    file_ops: list[Any] = []
+    tool_results: list[Any] = []
+
+    thread_id = getattr(session_state, "thread_id", None) or getattr(
+        session_state, "session_id", None
+    )
+    holder = lease_holder("tui")
+
+    # Best-effort cross-process lease. Only acquired when we have a real
+    # thread_id; never blocks (proceeds unleased on conflict).
+    _lease_cm = lease_session(thread_id, holder) if thread_id else _null_async_cm()
+
+    async with _lease_cm:
+        async for event in run_with_goal(
+            user_input,
+            agent,
+            assistant_id,
+            session_state,
+            backend=backend,
+            image_tracker=image_tracker,
+            seen_message_ids=seen_message_ids,
+            skip_file_mentions=skip_file_mentions,
+            can_continue=can_continue,
+        ):
+            if verifier is not None:
+                if isinstance(event, ev.AssistantMessage):
+                    texts.append(event.text)
+                elif isinstance(event, ev.FileOp) and getattr(event, "record", None) is not None:
+                    file_ops.append(event.record)
+                elif isinstance(event, ev.ToolResult):
+                    tool_results.append(event)
+            yield event
+
+    if verifier is not None:
+        agent_output = "\n\n".join(t for t in texts if t).strip()
+        _spawn_verification_signal(
+            verifier, user_input, agent_output, file_ops, session_state, tool_results
+        )

novacode_cli/agents/agent_file.py

@@ -0,0 +1,250 @@
+"""Custom subagent definitions and the tools a subagent may be given.
+
+An ``agent.md`` is YAML frontmatter plus the system prompt::
+
+    ---
+    color: "#0ea5e9"
+    description: "Reviews Python for security bugs"
+    tools: ["web_search", "serena_find_symbol"]
+    ---
+    You are ...
+
+``tools`` is optional. Absent means every tool (what agents always had);
+a list means exactly those, on top of the file/shell tools every subagent gets
+from deepagents itself (:data:`ALWAYS_INCLUDED`).
+
+Create new definitions as flat ``.nova/agents/<name>.md`` files in a project or
+``~/.nova/agents/<name>.md`` globally. Existing ``<name>/agent.md`` folders and
+Claude Code agent files remain supported::
+
+    ---
+    name: approver
+    description: Final gate; writes decision.md.
+    tools: Read, Grep, Glob, Bash, Write
+    model: opus
+    ---
+
+Claude tool names map to Nova's (:data:`CLAUDE_TOOL_NAMES`). A list that names
+any file/shell tool is a Claude-style allowlist: the file/shell tools it leaves
+out are taken away (:class:`FilesystemToolFilter`), so ``approver`` has no
+``edit_file``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import ToolMessage
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from langchain.agents.middleware.types import ModelRequest, ModelResponse
+    from langchain.tools.tool_node import ToolCallRequest
+    from langgraph.types import Command
+
+#: Given to every subagent by deepagents' own middleware; not selectable.
+ALWAYS_INCLUDED = (
+    "ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep", "execute",
+)
+
+#: Claude Code tool names in an agent file's ``tools:`` → Nova's tool names.
+CLAUDE_TOOL_NAMES = {
+    "Read": "read_file",
+    "Write": "write_file",
+    "Edit": "edit_file",
+    "MultiEdit": "edit_file",
+    "NotebookEdit": "NotebookEditTool",
+    "Grep": "grep",
+    "Glob": "glob",
+    "GlobTool": "glob",
+    "GrepTool": "grep",
+    "LS": "ls",
+    "Bash": "execute",
+    "WebFetch": "fetch_url",
+    "WebSearch": "web_search",
+    "TodoWrite": "write_todos",
+}
+
+
+def _parse(content: str) -> tuple[dict[str, Any], str]:
+    if not content.startswith("---"):
+        return {}, content
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        return {}, content
+    front: dict[str, Any] = {}
+    try:
+        import yaml
+
+        loaded = yaml.safe_load(parts[1])
+        if isinstance(loaded, dict):
+            front = loaded
+    except Exception:  # noqa: BLE001 — hand-written files: fall back to key: value lines
+        for line in parts[1].splitlines():
+            if ":" in line:
+                key, value = line.split(":", 1)
+                front[key.strip()] = value.strip().strip('"').strip("'")
+    return front, parts[2].lstrip("\n")
+
+
+def _split(content: str) -> tuple[dict[str, Any], str]:
+    """Reuse parsed frontmatter by exact content, never resolved capabilities."""
+    from time import perf_counter_ns
+
+    from novacode_cli.computation_cache import digest, get, put, record_timing
+
+    started = perf_counter_ns()
+    key = digest("agent-definition-v1\0" + content)
+    record_timing("agent_definitions", "validation", perf_counter_ns() - started)
+    cached = get("agent_definitions", key)
+    if cached is not None:
+        cached = cast("list[Any]", cached)
+        return cached[0], cached[1]
+    started = perf_counter_ns()
+    front, body = _parse(content)
+    record_timing("agent_definitions", "computation", perf_counter_ns() - started)
+    if set(front) <= {"name", "description", "tools", "model", "color", "skill_names"}:
+        put("agent_definitions", key, [front, body])
+    return front, body
+
+
+def read_agent(path: Path) -> tuple[dict[str, Any], str]:
+    """``(frontmatter, system_prompt)`` of an ``agent.md``."""
+    return _split(path.read_text(encoding="utf-8"))
+
+
+def agent_tools(content: str) -> list[str] | None:
+    """The agent's chosen tool names, or None when it did not choose (= all)."""
+    tools = _split(content)[0].get("tools")
+    if tools is None:
+        return None
+    if isinstance(tools, str):
+        tools = [t.strip() for t in tools.split(",")]
+    names = [str(t).strip() for t in tools if str(t).strip()]
+    return list(dict.fromkeys(CLAUDE_TOOL_NAMES.get(n, n) for n in names))
+
+
+def filesystem_allowlist(chosen: list[str] | None) -> set[str] | None:
+    """The file/shell tools an agent keeps, or None when it keeps all of them.
+
+    Only a list naming at least one of them restricts: Nova's own agent files
+    never list them (the /agents picker hides them), so they keep every one.
+    """
+    allowed = set(chosen or ()) & set(ALWAYS_INCLUDED)
+    return allowed or None
+
+
+class FilesystemToolFilter(AgentMiddleware):
+    """Takes away the file/shell tools an agent's ``tools:`` list left out.
+
+    deepagents gives every subagent all of :data:`ALWAYS_INCLUDED`; this hides
+    the others from the model and refuses a call to one anyway.
+    """
+
+    def __init__(self, allowed: set[str]) -> None:
+        """Keep *allowed* of :data:`ALWAYS_INCLUDED`; block the rest."""
+        super().__init__()
+        self._blocked = set(ALWAYS_INCLUDED) - allowed
+
+    def _bind(self, request: ModelRequest) -> ModelRequest:
+        keep = [t for t in request.tools if getattr(t, "name", None) not in self._blocked]
+        return request.override(tools=keep)
+
+    def _refusal(self, request: ToolCallRequest) -> ToolMessage | None:
+        call = request.tool_call
+        if call["name"] not in self._blocked:
+            return None
+        return ToolMessage(
+            f"{call['name']} is not in this agent's tools.",
+            tool_call_id=call["id"],
+            name=call["name"],
+            status="error",
+        )
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        """Bind only the allowed file/shell tools."""
+        return handler(self._bind(request))
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelResponse:
+        """Bind only the allowed file/shell tools."""
+        return await handler(self._bind(request))
+
+    def wrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], ToolMessage | Command],
+    ) -> ToolMessage | Command:
+        """Refuse a blocked tool the model called anyway."""
+        return self._refusal(request) or handler(request)
+
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
+    ) -> ToolMessage | Command:
+        """Refuse a blocked tool the model called anyway."""
+        return self._refusal(request) or await handler(request)
+
+
+def write_agent(path: Path, front: dict[str, Any], body: str) -> None:
+    """Write ``agent.md``. Values are JSON-quoted, which is valid YAML: a
+    description holding ``: `` or a Windows path can no longer break it."""
+    lines = ["---"]
+    for key, value in front.items():
+        if value is None:
+            continue
+        lines.append(f"{key}: {json.dumps(value, ensure_ascii=False)}")
+    lines += ["---", "", body.strip(), ""]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def set_agent_tools(path: Path, tools: list[str] | None) -> None:
+    """Replace an agent's tool selection (None = back to every tool)."""
+    front, body = read_agent(path)
+    front.pop("tools", None)
+    if tools is not None:
+        front["tools"] = sorted(tools)
+    write_agent(path, front, body)
+
+
+def tool_arsenal(session_tools: list[Any] | None = None) -> list[tuple[str, str]]:
+    """Every selectable tool as ``(name, one-line description)``, sorted.
+
+    Nova's own tools come from the live session; MCP tools from the schema
+    cache of each enabled server (named ``<server>_<tool>``, as bound).
+    """
+    found: dict[str, str] = {}
+    for tool in session_tools or []:
+        name = getattr(tool, "name", None)
+        if name and name not in ALWAYS_INCLUDED:
+            found[name] = (getattr(tool, "description", "") or "").strip().split("\n")[0]
+    try:
+        from novacode_cli.mcp.config import MCPConfig
+        from novacode_cli.mcp.middleware import _load_schema_cache
+
+        enabled = {
+            name for name, cfg in MCPConfig().list_servers().items()
+            if not getattr(cfg, "disabled", False)
+        }
+        for server, entry in _load_schema_cache().items():
+            if server not in enabled or not isinstance(entry, dict):
+                continue
+            for raw in entry.get("tools") or []:
+                desc = (raw.get("description") or "").strip().split("\n")[0]
+                found[f"{server}_{raw.get('name')}"] = desc
+    except Exception:  # noqa: BLE001 — MCP listing is best effort
+        pass
+    return sorted(found.items())

novacode_cli/agents/agent_mailbox.py

@@ -0,0 +1,120 @@
+"""Agent-to-agent mailbox — a lightweight in-process message bus.
+
+Nova's subagents run synchronously (one at a time, via the `task` tool), so they
+can't hold a live conversation. This mailbox gives peer messaging instead: any
+agent (orchestrator or subagent) drops a message into another agent's inbox by
+name, and reads its own inbox when it runs. The orchestrator sequences the turns
+(dispatch A → A messages B → dispatch B → B reads + replies → A reads).
+
+Process-global and thread-safe: subagents run in the same process as the
+orchestrator, so a module-level store is all that's needed. It is NOT durable
+across restarts (a conversation lives within one session), by design.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+from langchain.tools import tool
+
+_lock = threading.RLock()
+# recipient agent name -> list of {"from": str, "text": str, "ts": float}
+_mailbox: dict[str, list[dict]] = {}
+_scoped_mailbox: dict[tuple[str, str, str, str], list[dict]] = {}
+_MAX_PER_INBOX = 100  # cap so a runaway loop can't grow memory unbounded
+
+
+@tool
+def send_agent_message(to_agent: str, message: str, from_agent: str = "orchestrator") -> str:
+    """Send a message to another agent's inbox (agent-to-agent communication).
+
+    Use this to hand a question, result, or instruction to a specific peer agent
+    by name. The recipient reads it with `read_agent_messages` when it next runs.
+
+    Args:
+        to_agent: The exact name of the recipient agent (e.g. "code-explorer").
+        message: The message to deliver.
+        from_agent: Your own agent name, so the recipient knows who wrote it.
+
+    Returns:
+        Confirmation that the message was queued.
+    """
+    to_agent = (to_agent or "").strip()
+    if not to_agent:
+        return "Error: to_agent is required."
+    from novacode_cli.teams.legacy import mailbox_identity
+
+    scope = mailbox_identity.get()
+    if scope is not None:
+        from_agent = scope[3]
+    with _lock:
+        inbox = (
+            _scoped_mailbox.setdefault((*scope[:3], to_agent), [])
+            if scope
+            else _mailbox.setdefault(to_agent, [])
+        )
+        if scope and (len(inbox) >= _MAX_PER_INBOX or len(message.encode()) > 16384):
+            return "Error: scoped inbox limit reached; read pending messages first."
+        inbox.append({"from": from_agent or "unknown", "text": message, "ts": time.time()})
+        if len(inbox) > _MAX_PER_INBOX:
+            del inbox[: len(inbox) - _MAX_PER_INBOX]
+    return f"Message delivered to '{to_agent}' inbox."
+
+
+@tool
+def read_agent_messages(as_agent: str, clear: bool = True) -> str:
+    """Read messages addressed to you (agent-to-agent communication).
+
+    Args:
+        as_agent: Your own agent name — the inbox to read.
+        clear: When True (default), consume the messages so they aren't re-read.
+
+    Returns:
+        The messages addressed to you, newest last, or "No messages.".
+    """
+    as_agent = (as_agent or "").strip()
+    if not as_agent:
+        return "Error: as_agent is required (pass your own agent name)."
+    from novacode_cli.teams.legacy import mailbox_identity
+
+    scope = mailbox_identity.get()
+    with _lock:
+        if scope:
+            if as_agent != scope[3]:
+                return "Error: cannot read another agent's inbox."
+            msgs = list(_scoped_mailbox.get(scope, []))
+            if clear:
+                _scoped_mailbox.pop(scope, None)
+        else:
+            msgs = list(_mailbox.get(as_agent, []))
+            if clear:
+                _mailbox[as_agent] = []
+    if not msgs:
+        return "No messages."
+    return "\n".join(f"[from {m['from']}] {m['text']}" for m in msgs)
+
+
+def clear_mailbox() -> None:
+    """Drop every inbox (used on /clear so a new conversation starts empty)."""
+    with _lock:
+        _mailbox.clear()
+
+
+if __name__ == "__main__":
+    clear_mailbox()
+    assert send_agent_message.invoke({"to_agent": "b", "message": "hi B", "from_agent": "a"}).startswith(
+        "Message delivered"
+    )
+    assert read_agent_messages.invoke({"as_agent": "b"}) == "[from a] hi B"
+    assert read_agent_messages.invoke({"as_agent": "b"}) == "No messages."  # cleared
+    assert read_agent_messages.invoke({"as_agent": "nobody"}) == "No messages."
+    print("agent_mailbox self-check ok")
+
+
+def clear_scoped_mailbox(project: str, root: str) -> None:
+    """Release one root's legacy inboxes after its owned workers stop."""
+    with _lock:
+        for key in list(_scoped_mailbox):
+            if key[:2] == (project, root):
+                _scoped_mailbox.pop(key, None)