kdaip/echobot/echobot-development

EchoBot Development

Work inside the current repository layout. Keep changes small, readable, and shared across CLI, gateway, and app entrypoints.

Start here

• Read AGENTS.md before 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, or echobot/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.py or echobot/orchestration/route_modes.py for route selection only.
• Change echobot/orchestration/roleplay.py for visible persona replies, delegated acknowledgements, and final presentation only.
• Change echobot/agent.py, echobot/runtime/session_runner.py, or echobot/runtime/turns.py for background agent behavior, tools, skills, memory, and scheduling.
• Change echobot/tools/ or echobot/skill_support/ instead of duplicating tool or skill wiring in one entrypoint.
• Change echobot/commands/ and echobot/cli/session_commands.py for /route, /runtime, /role, and session command behavior.
• Change echobot/app/routers/, echobot/app/services/, and echobot/app/web/ for HTTP or browser UI behavior.

Practical workflow

1. Locate the entrypoint and the owning layer.
2. Trace shared wiring through build_runtime_context(...), ConversationCoordinator, and SessionAgentRunner.
3. Make the smallest coherent change.
4. Add or update focused tests under tests/.
5. 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 under skills/.
• 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.