A shared loop.
Explicit boundaries.

01System map

A task can enter through a CLI launcher or the Web UI. A configured Agent may work alone or dispatch children when its roster and permissions allow it. MetaAgent is an Agent with delegation capabilities; it is not a mandatory extra process around every Builder.

02Entry and process ownership

The Web UI sends versioned commands through the Gateway WebSocket. HTTP views, terminals, environment streams and published sites use the Gateway’s corresponding proxy routes. CLI launchers can start the runtime directly and register their monitor through the deployment service.

The base Agent.prepare_task binds task text, files and public manifest declarations. Runtime owns process creation, mailboxes, signals, parent/child relationships, topics and exit cleanup. Task and session managers own the persistent task and workspace identities.

NEW → RUNNING ⇄ IDLE
        ↕        ↕
        SUSPENDED
          ↓
       STOPPING → EXITED

One-shot work exits with a report. Resident subscribers can remain idle between assignments. Local assignment limits and the shared root/descendant budget ledger are separate: delegation does not reset the total run budget.

agentevolver/runtime/kernel.py · agentevolver/runtime/process.py

03The shared think–act loop

Agent preparation installs the system prompt, task anchor and allowed capability surface. Each step collects current state, checks budgets and context pressure, asks the model, then routes its actions. Lifecycle hooks expose the same boundaries to tracing and other observers.

process safe point
  → current state + budget guards
  → context assembly / history compaction when needed
  → ModelManager request
  → ToolRouter + ActionExecutor
  → observations + complete conversation turn

Managers supply capability discovery and schemas; the router enforces scope and dispatches calls. Environments return state and, when configured, images through the shared context path. A Builder does not need a separate screenshot-message pipeline.

For the Docker Godot demo, the base execution container and Godot container mount the same workspace paths. Bash edits project files; the Godot environment imports, launches and interacts with the game. Deployment creates a separate browser playtest with its own saves.

agentevolver/agent/loop/agent.py
agentevolver/agent/loop/router.py

04Context, plans and memory

ContextAssembler owns request layout. Stable material leads the request so appending a turn or refreshing an observation does not rewrite the earlier prefix. Cache behavior still depends on the selected provider and request.

Planning-enabled coordinators keep plan/index.md and plan/plan.md. Only the bounded index and document locators are automatically projected into live context. The detailed plan and any evaluations, designs or playtest notes are read on demand. Skills can suggest a directory layout; the generic module requires only these two files.

History compaction keeps recent complete turns and preserves a source archive for disk-backed threads. Fixed instructions and automatic live projections are outside its input. Explicit tool reads of a plan are ordinary history. Session-scoped actor notes provide a separate durable index; they are not silently shared between sessions or actors.

The website and game demos configure a 100,000-input-token compaction trigger. This estimates the full request, including cached input, schemas and images; it is not “compact every 100,000 tokens spent.” Cumulative token limits, step limits and context capacity are different controls.

agentevolver/agent/context/assembler.py
agentevolver/plan/server.py · agentevolver/memory/README.md

05Records and product access

Trace stores structured execution events. Run and request viewers project those records into human-readable steps, errors, usage and context diagnostics. Checkpoints restore supported conversation state; they do not reconstruct running OS jobs or engine processes.

deploy_tool delegates publication and lifecycle to the deployment manager. Websites and Godot previews have stable site URLs through the Gateway; archived releases have pinned URLs. CLI run monitors are registered at port 9876, with product links in their deployments view.

Trajectory is a training-oriented projection: model context, actions, observations and usage, with optional reward backfill and SFT / RL export. A dataset export is not a training execution or automatic model promotion.

agentevolver/visual/README.md · agentevolver/deploy/README.md · agentevolver/trajectory/README.md

06A versioned capability, with evidence

The shared evolution rules and self_evolving_skill guide an agent from observations to an experiment. Signals include a concrete opportunity for a better reusable method, a structural failure or a measured quality/cost limitation. A missing product feature alone does not establish a missing system capability.

1. 1. Observe and establish a baselineInspect available capabilities. Record the actual need, relevant call evidence, intended consumer and a measurable comparison.
2. 2. Author the appropriate componentUse a skill, tool, agent/prompt, workflow, environment, memory, connector or plugin. Author outside the core and preserve the baseline.
3. 3. Register a separate candidateadoption_tool performs registration through ExtensionManager. Structural admission checks loading, construction and schemas in isolation; the returned candidate version identifies what to evaluate.
4. 4. Evaluate that versionExecute baseline/candidate comparison and independent reuse or regression cases, with cost. Record real call IDs and observed results. A successful structural probe is not functional evaluation.
5. 5. Record and carry out the decisionKeep requires a passing version-scoped report. Otherwise record rollback or unload and execute that operation. Registration may make a candidate provisionally available; it is not a quality certificate.
6. 6. Use the adopted versionVerify the actual consumer result. Tasks requiring verified improvement also require record_use after keep, with subsequent real-work call receipts. Loading a skill without executing its method is insufficient.

agentevolver/prompt/module/evolution_rules.html
agentevolver/tool/default/adoption.py · agentevolver/extension/server.py

07Controls and limits

agentevolver/permission/README.md · agentevolver/runtime/process.py