Skip to content

AGENTS.md

Latest commit

 

History

History
94 lines (73 loc) · 5.5 KB

AGENTS.md

File metadata and controls

94 lines (73 loc) · 5.5 KB
Raw

AGENTS.md

This file provides guidance to We0 Cli when working with code in this repository.

Repo Coding Conventions

  • Prefer pydantic models or TypedDict-style typed structures over passing raw untyped dict objects through the system.
  • Avoid getattr for normal application flow. Prefer explicit typed fields, dedicated adapter/helper methods, or small boundary objects. Reserve getattr for true dynamic interop boundaries such as plugin hooks, third-party SDK objects, or narrowly scoped test shims.
  • Prefer class + @staticmethod helper organization over scattered free functions when the logic belongs to a parser, loader, or service domain.
  • Reuse existing repository patterns and elegant implementations before introducing a new parsing or loading approach.
  • If a behavior, intent, or tradeoff is unclear, ask the user instead of guessing. The user is willing to clarify.
  • Favor object-oriented structure for runtime and service code.
  • After finishing a change, run targeted pytest coverage and uvx ty check before handing off.

Development commands

This project is a Python CLI package (agent-loop) with entrypoint we0.

Environment setup

  • Create venv: python3 -m venv .venv
  • Activate: source .venv/bin/activate
  • Install package + dev deps: pip install -e . ".[images]" pytest pytest-asyncio

Run the CLI locally

  • Module mode: python -m we0_agent
  • Installed script mode: we0

Tests

  • Run all tests: pytest
  • Run a test file: pytest tests/ui/shell/test_shell_app.py
  • Run a single test: pytest tests/ui/shell/test_shell_app.py::test_<name>
  • Run tests by keyword: pytest -k "session and prompt"

Project-specific checks

  • Import guard script: python scripts/check_imports.py

High-level architecture

1) Package layout

  • Main code: we0_agent/
  • Tests: tests/
  • Utility/maintenance scripts: scripts/

Within we0_agent/, structure is organized by responsibility:

  • we0_agent/__main__.py: CLI entrypoint and process startup.
  • we0_agent/core/: runtime orchestration and domain services.
  • we0_agent/common/: shared entities, settings, constants, exceptions, and shared clients.

2) Session runtime (core loop)

The central execution path is under we0_agent/core/session/.

Key components:

  • session.py: session lifecycle and top-level coordination.
  • processor.py: processes user input / events and drives tool-use flow.
  • llm.py: model interaction layer.
  • prompt.py + system.py: prompt assembly and system-instruction injection.
  • compaction.py: context/message compaction logic for long-running sessions.
  • tool_activation.py + tool_resolver.py: determines which tools are active and resolvable in-context.
  • task.py, todo.py, cron.py, revert.py, status.py, thinking_state.py: runtime state features exposed to the agent/user flow.

This folder is the primary place to inspect when behavior changes involve prompt composition, tool calling, context management, or conversation-state transitions.

3) Core subsystems outside session

  • we0_agent/core/project/: project bootstrap/state/instance management.
  • we0_agent/core/permission/: permission checks plus wildcard/arity handling.
  • we0_agent/core/question/: interactive question/choice handling.
  • we0_agent/core/skills/: skill discovery and watcher/scanner logic.

4) Shared domain models and settings

  • we0_agent/common/domain/entities/: typed domain entities (tasks, todos, loop input, permission, question, model/skill cards, bus messages).
  • we0_agent/common/settings/settings.py: runtime configuration loading.
  • we0_agent/common/constants/: shared Constants.
  • we0_agent/common/exceptions/: exception types.

When changing interfaces between runtime components, check entities first to keep data contracts consistent.

5) Test organization

Tests mirror runtime domains and are a guide to intended behavior:

  • tests/core/session/: prompt composition, compaction, tool activation/resolution, processor behavior, revert/reasoning/image handling.
  • tests/core/: lower-level core services (e.g., MCP manager, logging, background progress, LSP builtin behavior).
  • tests/ui/shell/: CLI/shell interaction surface and UX-oriented behaviors (slash commands, transcript, tasks panel, visualization, clipboard, questions).
  • tests/common/: shared/common utility behavior.

For regressions, start with the closest mirrored test area, then run narrower test targets before full-suite runs.

6) New UI Rewrite Rules

  • New TUI rewrite work lives under we0_agent/new_ui/. Treat we0_agent/ui/ as legacy reference unless the task is an explicit old-UI bug fix.
  • Until the user explicitly asks for cutover or legacy bugfix wiring, do not add new rewrite logic, bridges, mirrors, adapters, or state derivation into we0_agent/ui/*. Keep those inside we0_agent/new_ui/* only.
  • Preserve the current TUI visual style and interaction semantics. Rewrite structure, not product behavior.
  • Do not hot-insert children into a renderer-owned root tree. Build a single explicit page tree instead.
  • The page tree should be modeled as Viewport -> Body -> PanelSlot -> OverlayLane -> InputDock -> FooterDock -> ModalLayer.
  • Do not use prompt message / bottom_toolbar callbacks as a surrogate page layout in new code.
  • Resize handling in new UI must rely on layout invalidation and renderer diffing. Do not use transcript re-printing or run_in_terminal(...) repaint fallbacks.
  • Keep modal selectors (/model, /resume, rewind, standalone /btw) as explicit modal surfaces, not ad-hoc prompt/live overlays.