Building on AgentEvolver

01Setup

One environment, two commands. The gateway serves the runtime; the Vite dev server serves the UI and reverse-proxies to the gateway, so only one port ever needs forwarding.

pip install -e ".[dev]"

# terminal 1 — the runtime
python -m agentevolver.cli serve --transport websocket --port 9876

# terminal 2 — the UI (proxies /ws to the gateway)
cd frontend && npm install && npm run dev

02Repository layout

Every capability lives in its own top-level module under agentevolver/. There is no shared "core" that things get added to — a new capability is a new directory, and nothing else changes.

03The module contract

A module is four files, and the shape is uniform enough that finding your way around an unfamiliar one takes no reading.

agentevolver/<module>/
  README.md      # YAML frontmatter + what this module owns  (gated)
  types.py       # the data and the contract — no I/O
  server.py      # the singleton manager: register / get / list / unregister
  __init__.py    # the public surface

Registration is by class field

A tool, agent, or environment is discovered by its name class field, not by an argument passed to a constructor. Passing it any other way registers as None, and nothing complains until the model cannot find the capability.

04Adding a capability

A tool is one thing an agent can do. The procedure below is the whole of it; agents, skills, and environments follow the same three steps against their own manager.

class WordCountTool(Tool):
    """Count the words in a file."""

    name: str = Field(default="word_count")            # class field — see above
    description: str = Field(default="Count words in a UTF-8 text file.")
    mutates: bool = Field(default=False)               # three-valued; see below

    async def __call__(self, path: str, ctx=None, **kwargs) -> Response:
        with open(path, encoding="utf-8") as handle:
            count = len(handle.read().split())
        return Response(type=ResponseType.TOOL, success=True,
                        message=f"{count} words", data={"words": count})

1. Write the class in agentevolver/tool/default/.
2. Export it from that package's __init__.py. Discovery is by import; a tool that is written and not exported is invisible and nothing reports it.
3. Test it, covering the failure path — a model cannot tell "this file does not exist" from "this tool is broken" unless the message says so.

The description is a model-facing contract, not a label. "Count the words in a UTF-8 text file" tells a model when to reach for it; "Word counting utility" does not.

05Gateway and frontend

The browser reaches the runtime through one WebSocket and nothing else. A command is {id, method, params, protocol_version}; the server answers with a response of the same id, and pushes ordered events alongside.

Adding a method is one function. The dispatcher maps method to _command_<name>, so docs.list is served by _command_docs_list. No table to register in.

06Extensions at runtime

Components can be created, versioned, promoted, and rolled back while the system runs. Two mechanisms make that safe rather than merely possible.

Promotion — turning a file an agent wrote into a file the next session loads as code — checks containment after resolving both paths, so a traversal cannot be spelled with .. or hidden behind a symlink.

07Verification

Two lanes. The ordinary one is fast; the measured one costs about 30% more wall-clock and answers a question no individual test can.

pytest              # the ordinary run
pytest --cov        # measures, then applies the coverage gate

The gate is a dark-file register, not a percentage

The rule is not the number. It is the set of files the whole suite never executes a line of — a set that holds two things wearing the same clothes: code nothing tests, and code nothing calls. Every file at zero must be named in a register with the reason a test cannot reach it.

A check that cannot fail is worse than no check

Consistency checks are themselves guarded: a suite reintroduces each real defect in a subprocess and requires the check to go red. A check that always passes reports the invariant as held, silently, forever.

08Decisions and postmortems

Code says what happens; tests say what must keep happening. Neither says why the third option lost, and that is what gets re-litigated.

The test for writing one is simple: would someone reasonably ask "why was this done this way?" in six months? That is a lower bar than "was this hard" and a much higher one than "did I change something".

Both trees live beside the code and are checked by the same gates as everything else: decisions/ · postmortems/ · cookbook/ · DOC-STANDARD.md

09Invariants that were paid for

Each of these is a rule that exists because its absence produced a defect. They are collected here because every one of them is easy to undo by accident.