kdaip EchoBot Development
Work inside the current repository layout. Keep changes small, readable, and shared across CLI, gateway, and app entrypoints.
Start here
- Read
AGENTS.mdbefore non-trivial changes. - Keep Python 3.11+ code beginner-friendly. Prefer
pathlib. Keep one clear responsibility per function or class. - Do not block the event loop. Move blocking file, network, or CPU-heavy work to
asyncio.to_thread(...)or an executor. - Find the real entrypoint first:
echobot/cli/main.py,echobot/cli/chat.py,echobot/cli/gateway.py,echobot/cli/app.py, orechobot/app/create_app.py. - Reuse the shared runtime assembly in
echobot/runtime/bootstrap.py. If a feature should exist in chat, gateway, and app, wire it there once.
Choose the right layer
- Change
echobot/orchestration/decision.pyorechobot/orchestration/route_modes.pyfor route selection only. - Change
echobot/orchestration/roleplay.pyfor visible persona replies, delegated acknowledgements, and final presentation only. - Change
echobot/agent.py,echobot/runtime/session_runner.py, orechobot/runtime/turns.pyfor background agent behavior, tools, skills, memory, and scheduling. - Change
echobot/tools/orechobot/skill_support/instead of duplicating tool or skill wiring in one entrypoint. - Change
echobot/commands/andechobot/cli/session_commands.pyfor/route,/runtime,/role, and session command behavior. - Change
echobot/app/routers/,echobot/app/services/, andechobot/app/web/for HTTP or browser UI behavior.
Practical workflow
- Locate the entrypoint and the owning layer.
- Trace shared wiring through
build_runtime_context(...),ConversationCoordinator, andSessionAgentRunner. - Make the smallest coherent change.
- Add or update focused tests under
tests/. - Run the narrowest useful test group first, then expand if the change crosses subsystem boundaries.
Shared runtime rules
- Keep one source of truth for sessions, tools, skills, route modes, runtime settings, and scheduling.
- Extend
create_basic_tool_registry(...)or the tool-registry factory instead of hand-building tool lists for one surface. - Keep skill behavior inside
echobot/skill_support/and repository-local skills underskills/. - Preserve the separation between user-facing roleplay context and background agent execution context.
- Use
json.dumps(..., ensure_ascii=False)for JSON output. - When changing a project skill, validate it with
python -X utf8 echobot/skills/skill-creator/scripts/quick_validate.py skills/<skill-name>.
Focused tests
- Skills or skill runtime:
python -m unittest tests.test_skill_support tests.test_chat_agent -v - Agent loop, tools, or traces:
python -m unittest tests.test_agent tests.test_tools tests.test_agent_traces -v - Routing, coordinator, or roleplay:
python -m unittest tests.test_decision tests.test_coordinator tests.test_roleplay tests.test_roles -v - Commands, gateway, or API:
python -m unittest tests.test_commands tests.test_gateway tests.test_app_api -v - Sessions, settings, or scheduler:
python -m unittest tests.test_sessions tests.test_config tests.test_scheduler -v - Images, attachments, or TTS:
python -m unittest tests.test_images tests.test_channel_images tests.test_tts -v
Read references/architecture.md before changing more than one subsystem or any shared runtime path.