feat: config-driven architecture, install wizard, live runtime switching, usage tracking, auto-failover
Major changes: - Config-driven adapters: all channels (Slack, Discord, Telegram, WebChat, Webhooks) controlled via config.json with enabled flags and token auto-detection, no CLI flags required - Runtime engine field: runtime.engine selects opencode/claude from config - Interactive install script: 8-phase setup wizard with AI runtime detection/installation, token setup, identity file personalization (personality presets), aetheel CLI command, background service (launchd/systemd) - Live runtime switching: /engine, /model, /provider commands hot-swap the AI runtime from chat without restart, changes persisted to config.json - Usage tracking: per-request cost extraction from Claude Code JSON output, cumulative stats via /usage command - Auto-failover: rate limit detection on both runtimes, automatic switch to other engine on quota errors with user notification - Chat commands work without / prefix (Slack intercepts / in channels), commands: engine, model, provider, config, usage, reload, cron, subagents, status, help - /config set for editing config.json from chat with dotted key notation - Security audit saved to docs/security-audit.md - Full command reference in docs/commands.md - Future changes doc with NanoClaw agent teams analysis - Logo added to README and WebChat UI - README fully rewritten with all features documented
This commit is contained in:
214
docs/future-changes.md
Normal file
214
docs/future-changes.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Future Changes
|
||||
|
||||
Planned features and architectural improvements for Aetheel.
|
||||
|
||||
---
|
||||
|
||||
## Agent Teams & Delegation
|
||||
|
||||
The current subagent system spawns generic background workers that share the main agent's identity. The goal is to evolve this into a proper agent team architecture where specialized agents with their own roles, tools, and identity files can be created and coordinated.
|
||||
|
||||
### Vision
|
||||
|
||||
A main agent (e.g. "CTO") talks to the user and delegates tasks to specialist agents (e.g. "Programmer", "Designer") that each have their own personality, tool access, and domain expertise. Results flow back through the main agent or directly to the channel.
|
||||
|
||||
```
|
||||
User ──► Main Agent (CTO)
|
||||
│
|
||||
├──► Programmer Agent
|
||||
│ • Own SOUL.md (code-focused personality)
|
||||
│ • Tools: Bash, Read, Write, Edit, Grep
|
||||
│ • Model: claude-sonnet for speed
|
||||
│
|
||||
├──► Designer Agent
|
||||
│ • Own SOUL.md (design-focused personality)
|
||||
│ • Tools: WebSearch, WebFetch, Read
|
||||
│ • Model: claude-opus for creativity
|
||||
│
|
||||
└──► Researcher Agent
|
||||
• Own SOUL.md (thorough, citation-heavy)
|
||||
• Tools: WebSearch, WebFetch
|
||||
• Model: gemini-2.5-pro for large context
|
||||
```
|
||||
|
||||
### What Exists Today
|
||||
|
||||
- `SubagentManager` spawns background tasks via `[ACTION:spawn|<task>]`
|
||||
- `SubagentBus` provides pub/sub messaging between subagents
|
||||
- Claude Code's `Task`, `TaskOutput`, `TeamCreate`, `SendMessage` tools are already in the allowed tools list
|
||||
- All subagents currently share the same identity files (SOUL.md, USER.md, MEMORY.md)
|
||||
|
||||
### How NanoClaw Does It
|
||||
|
||||
NanoClaw (the inspiration project) takes a fundamentally different approach — container-based isolation with per-group identity:
|
||||
|
||||
**Architecture:**
|
||||
- Each chat group gets its own folder (`groups/{name}/`) with its own `CLAUDE.md` (identity/memory)
|
||||
- A `groups/global/CLAUDE.md` provides shared context readable by all groups
|
||||
- Each agent runs inside an Apple Container (lightweight Linux VM) with only its own folder mounted
|
||||
- The main channel has elevated privileges (can manage groups, write global memory, schedule tasks for any group)
|
||||
- Non-main groups can only access their own folder + read-only global memory
|
||||
|
||||
**Agent Teams (Swarm):**
|
||||
- Claude Code has native `TeamCreate`, `SendMessage` tools for multi-agent orchestration
|
||||
- NanoClaw enables this via `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` env var in the container
|
||||
- The lead agent creates teammates using Claude's built-in team tools
|
||||
- Each teammate gets instructions to use `send_message` with a `sender` parameter
|
||||
- On Telegram, each sender gets a dedicated bot identity (pool of pre-created bots renamed dynamically)
|
||||
- The lead agent coordinates but doesn't relay every teammate message — users see them directly
|
||||
|
||||
**Key design decisions:**
|
||||
- Identity is per-group, not per-agent — a "programmer" agent in one group is different from a "programmer" in another
|
||||
- The AI itself decides when to create teams and how to structure them — it's not pre-configured
|
||||
- Container isolation means agents can't read each other's files or sessions
|
||||
- IPC is file-based (JSON files in a watched directory), not in-memory pub/sub
|
||||
- Secrets are passed via stdin, never mounted as files
|
||||
|
||||
### What Needs to Be Built
|
||||
|
||||
#### 1. Agent Definitions
|
||||
|
||||
A new `agents/` directory in the workspace where each agent gets its own folder:
|
||||
|
||||
```
|
||||
~/.aetheel/workspace/agents/
|
||||
├── programmer/
|
||||
│ ├── AGENT.md # Role, description, triggers
|
||||
│ ├── SOUL.md # Agent-specific personality
|
||||
│ └── SKILL.md # Optional: domain-specific skills
|
||||
├── designer/
|
||||
│ ├── AGENT.md
|
||||
│ ├── SOUL.md
|
||||
│ └── SKILL.md
|
||||
└── researcher/
|
||||
├── AGENT.md
|
||||
└── SOUL.md
|
||||
```
|
||||
|
||||
`AGENT.md` frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: programmer
|
||||
description: Senior software engineer specializing in Python and system design
|
||||
triggers: [code, implement, build, fix, debug, refactor, PR]
|
||||
model: anthropic/claude-sonnet-4-20250514
|
||||
engine: claude
|
||||
tools: [Bash, Read, Write, Edit, Glob, Grep]
|
||||
max_turns: 5
|
||||
---
|
||||
```
|
||||
|
||||
#### 2. Agent-Aware Routing
|
||||
|
||||
The main agent decides which specialist to delegate to based on:
|
||||
- Explicit user request ("ask the programmer to...")
|
||||
- Trigger word matching from AGENT.md
|
||||
- AI-driven routing (the main agent's system prompt tells it about available agents)
|
||||
|
||||
New action tag: `[ACTION:delegate|<agent_name>|<task>]`
|
||||
|
||||
#### 3. Per-Agent Identity
|
||||
|
||||
Each agent gets its own system prompt built from:
|
||||
1. Its own `SOUL.md` (personality/role)
|
||||
2. Shared `USER.md` (user context is universal)
|
||||
3. Shared `MEMORY.md` (long-term memory is universal)
|
||||
4. Its own skills from `SKILL.md`
|
||||
5. Its tool restrictions from `AGENT.md`
|
||||
|
||||
#### 4. Agent-to-Agent Communication
|
||||
|
||||
Extend `SubagentBus` to support:
|
||||
- Named channels per agent (not just task IDs)
|
||||
- Request/response patterns (agent A asks agent B, waits for reply)
|
||||
- Broadcast messages (main agent sends context to all agents)
|
||||
- Result aggregation (main agent collects results from multiple agents)
|
||||
|
||||
#### 5. Team Orchestration Patterns
|
||||
|
||||
- **Sequential**: Programmer writes code → Designer reviews UI → Main agent summarizes
|
||||
- **Parallel**: Programmer and Designer work simultaneously, main agent merges results
|
||||
- **Supervisory**: Main agent reviews each agent's output before sending to user
|
||||
- **Collaborative**: Agents can message each other directly via the bus
|
||||
|
||||
#### 6. Chat Commands
|
||||
|
||||
```
|
||||
team list # List defined agents
|
||||
team status # Show which agents are active
|
||||
team create <name> # Interactive agent creation
|
||||
team remove <name> # Remove an agent definition
|
||||
delegate <agent> <task> # Manually delegate to a specific agent
|
||||
```
|
||||
|
||||
#### 7. Claude Code Native Teams
|
||||
|
||||
Claude Code already has `TeamCreate`, `TeamDelete`, `SendMessage` tools. These allow the AI itself to create and manage teams during a session. The integration path:
|
||||
|
||||
- When using Claude Code engine, the AI can use these tools natively
|
||||
- Aetheel wraps the results and routes messages back to the right channel
|
||||
- Agent definitions in `AGENT.md` pre-configure teams that get created on startup
|
||||
|
||||
### Implementation Priority
|
||||
|
||||
There are two paths — pick based on complexity appetite:
|
||||
|
||||
**Path A: Lightweight (extend current SubagentManager)**
|
||||
1. Agent definition format (`AGENT.md`) and discovery
|
||||
2. Per-agent identity file loading (own SOUL.md, shared USER.md/MEMORY.md)
|
||||
3. `[ACTION:delegate|agent|task]` tag parsing
|
||||
4. Agent-specific system prompt building with tool restrictions
|
||||
5. Chat commands for team management
|
||||
6. Agent-to-agent communication via extended bus
|
||||
|
||||
**Path B: Full isolation (NanoClaw-style containers)**
|
||||
1. Enable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` for Claude Code runtime
|
||||
2. Per-group workspace folders with own CLAUDE.md
|
||||
3. Container-based agent execution (Docker or Apple Container)
|
||||
4. File-based IPC between host and containers
|
||||
5. Mount security (allowlist, per-group isolation)
|
||||
6. Bot pool for Telegram/Discord (each agent gets its own bot identity)
|
||||
7. Lead agent orchestration via Claude's native team tools
|
||||
|
||||
Path A is simpler and works today. Path B is more secure and scalable but requires container infrastructure.
|
||||
|
||||
### NanoClaw Reference Files
|
||||
|
||||
Key files to study in `inspirations/nanoclaw/`:
|
||||
- `src/container-runner.ts` — Container spawning, volume mounts, IPC, per-group isolation
|
||||
- `src/types.ts` — `RegisteredGroup`, `ContainerConfig`, `AdditionalMount` types
|
||||
- `groups/global/CLAUDE.md` — Global identity shared across all groups
|
||||
- `groups/main/CLAUDE.md` — Main channel with elevated privileges
|
||||
- `.claude/skills/add-telegram-swarm/SKILL.md` — Full agent swarm implementation for Telegram
|
||||
- `docs/SPEC.md` — Complete architecture spec
|
||||
- `docs/SECURITY.md` — Security model for container isolation
|
||||
|
||||
---
|
||||
|
||||
## Other Planned Changes
|
||||
|
||||
### Security Fixes (from security-audit.md)
|
||||
|
||||
- Path containment check in `memory/manager.py` `read_file()`
|
||||
- Mandatory webhook auth when enabled
|
||||
- Input schema validation on webhook POST bodies
|
||||
- Stricter cron expression validation
|
||||
- Rate limiting on HTTP endpoints
|
||||
- WebSocket authentication for WebChat
|
||||
- Dependency version pinning
|
||||
|
||||
### Persistent Usage Stats
|
||||
|
||||
Currently usage stats reset on restart. Persist to SQLite so `usage` command shows lifetime stats, daily/weekly/monthly breakdowns, and cost trends.
|
||||
|
||||
### Multi-Model Routing
|
||||
|
||||
Route different types of requests to different models automatically:
|
||||
- Quick questions → fast/cheap model (sonnet, gpt-4o-mini)
|
||||
- Complex reasoning → powerful model (opus, o1)
|
||||
- Large context → big-context model (gemini-2.5-pro)
|
||||
|
||||
### Conversation Branching
|
||||
|
||||
Allow users to fork a conversation into a new thread with a different model or agent, then merge results back.
|
||||
Reference in New Issue
Block a user