ayder-cli 1.0__tar.gz → 1.6.1__tar.gz

{ayder_cli-1.0 → ayder_cli-1.6.1}/.gitignore

@@ -17,6 +17,9 @@ htmlcov/
 # macOS files
 .DS_Store
 
+# Git worktrees
+.worktrees/
+
 # Virtual environments
 .venv
 TODO

{ayder_cli-1.0 → ayder_cli-1.6.1}/AGENTS.md

@@ -35,6 +35,7 @@ This document provides coding standards, tool configurations, and workflows for
 | **pytest-cov** | Code coverage | >=7.0.0 |
 | **ruff** | Fast Python linter | latest |
 | **mypy** | Static type checker | latest |
+| **pyright** | Static type checker (Microsoft) | >=1.1.0 |
 | **uv** | Fast Python package manager | >=0.10.0 |
 | **poethepoet** | Task runner | >=0.24.0 |
 
@@ -61,21 +62,31 @@ ayder-cli/
 │   │   ├── context.py          # ProjectContext (path sandboxing)
 │   │   └── result.py           # ToolSuccess/ToolError types
 │   │
+│   ├── agents/                 # Multi-agent system
+│   │   ├── __init__.py         # Package exports
+│   │   ├── callbacks.py        # AgentCallbacks (ChatCallbacks for agents)
+│   │   ├── config.py           # AgentConfig (Pydantic model)
+│   │   ├── registry.py         # AgentRegistry (lifecycle management)
+│   │   ├── runner.py           # AgentRunner (isolated ChatLoop execution)
+│   │   ├── summary.py          # AgentSummary (structured result)
+│   │   └── tool.py             # call_agent tool definition + handler
+│   │
 │   ├── application/            # Shared application layer (CLI + TUI)
 │   │   ├── execution_policy.py         # ExecutionPolicy, PermissionDeniedError
 │   │   ├── message_contract.py         # LLM message format contracts
-│   │   ├── runtime_factory.py          # create_runtime() composition root
+│   │   ├── runtime_factory.py          # create_runtime() + create_agent_runtime()
 │   │   ├── temporal_contract.py        # Temporal workflow contracts
 │   │   ├── temporal_metadata.py        # Temporal metadata types
 │   │   └── validation.py              # ValidationAuthority, SchemaValidator
 │   │
-│   ├── loops/                  # Shared agent loop base
+│   ├── loops/                  # Shared agent loop + base classes
 │   │   ├── base.py             # AgentLoopBase (iteration, checkpoint, routing)
+│   │   ├── chat_loop.py        # ChatLoop (async LLM + tool execution loop)
 │   │   └── config.py           # Shared LoopConfig dataclass
 │   │
 │   ├── providers/              # LLM provider implementations
 │   │   ├── base.py             # AIProvider protocol, NormalizedStreamChunk
-│   │   ├── provider_orchestrator.py  # Factory: create(config) → provider
+│   │   ├── orchestrator.py  # Factory: create(config) → provider
 │   │   └── impl/               # Individual provider drivers
 │   │       ├── openai.py       # OpenAIProvider (base for most drivers)
 │   │       ├── ollama.py       # OllamaProvider (native + XML fallback)
@@ -86,9 +97,7 @@ ayder-cli/
 │   │       └── glm.py          # GLMNativeProvider (ZhipuAI SDK)
 │   │
 │   ├── services/               # Service layer
-│   │   ├── interactions.py     # InteractionSink, ConfirmationPolicy protocols
-│   │   └── tools/
-│   │       └── executor.py     # ToolExecutor (CLI confirmation + diff preview)
+│   │   └── interactions.py     # InteractionSink protocol (LLM debug events)
 │   │
 │   ├── tools/                  # Tool framework + implementations (25 tools)
 │   │   ├── definition.py       # ToolDefinition dataclass + auto-discovery
@@ -108,12 +117,15 @@ ayder-cli/
 │   │       ├── utils_tools.py  # manage_environment_vars
 │   │       ├── web.py          # fetch_web
 │   │       ├── dbs_tool.py     # DBS RAG API tool
-│   │       └── temporal.py     # Temporal workflow tool
+│   │       ├── temporal.py     # Temporal workflow tool
+│   │       ├── tasks.py        # Task management (.ayder/tasks/)
+│   │       ├── notes.py        # Note management (.ayder/notes/)
+│   │       └── memory.py       # Cross-session memory storage
 │   │
 │   ├── tui/                    # Textual TUI (main interface)
 │   │   ├── __init__.py         # run_tui() entry point
 │   │   ├── app.py              # AyderApp main application
-│   │   ├── chat_loop.py        # TUI async chat loop (TuiChatLoop)
+│   │   ├── chat_loop.py        # Backward-compat re-exports → loops/chat_loop.py
 │   │   ├── commands.py         # Slash command handlers (19 commands)
 │   │   ├── helpers.py          # TUI helper functions
 │   │   ├── adapter.py          # TUIInteractionSink (verbose debug)
@@ -128,12 +140,9 @@ ayder-cli/
 │   │   ├── claude.py           # Claude theme CSS
 │   │   └── original.py         # Original theme CSS
 │   │
-│   ├── memory.py               # Cross-session memory storage
-│   ├── notes.py                # Note management (.ayder/notes/)
 │   ├── parser.py               # XML/JSON tool call parser
 │   ├── process_manager.py      # Background process management
 │   ├── prompts.py              # System prompt templates
-│   ├── tasks.py                # Task management (.ayder/tasks/)
 │   └── ui.py                   # Rich terminal UI helpers
 │
 ├── tests/                      # Test suite (998+ tests)
@@ -158,7 +167,8 @@ ayder-cli/
 | `cli.py` | Entry point, argument parsing |
 | `tui/app.py` | Main TUI application (AyderApp) |
 | `tui/commands.py` | Slash command handlers (19 commands) |
-| `tui/chat_loop.py` | Async LLM loop for TUI (TuiChatLoop + TuiCallbacks protocol) |
+| `loops/chat_loop.py` | Async LLM + tool execution loop (ChatLoop + ChatCallbacks protocol) |
+| `tui/chat_loop.py` | Backward-compat re-exports (TuiChatLoop → ChatLoop aliases) |
 | `cli_runner.py` | CLI command execution + sync agent loop |
 | `application/runtime_factory.py` | `create_runtime()` — single composition root for CLI + TUI |
 | `application/execution_policy.py` | Shared permission + tool execution policy |
@@ -168,7 +178,7 @@ ayder-cli/
 | `tools/registry.py` | ToolRegistry: schemas, execution, system prompts, tag filtering |
 | `core/config.py` | Configuration with Pydantic validation |
 | `core/context.py` | ProjectContext for path sandboxing |
-| `providers/provider_orchestrator.py` | Factory dispatching to correct driver |
+| `providers/orchestrator.py` | Factory dispatching to correct driver |
 
 ## Environment Setup
 
@@ -338,6 +348,10 @@ uv run poe typecheck
 uv run mypy src/
 ```
 
+## Type Checking with Pyright
+
+Use the **pyright-lsp LSP server** for Pyright diagnostics — do not run `pyright` as a CLI command. The LSP tool provides real-time type errors directly from the language server.
+
 ### Type Annotation Standards
 
 ```python

{ayder_cli-1.0 → ayder_cli-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ayder-cli
-Version: 1.0
+Version: 1.6.1
 Summary: AI agent for any LLMs
 Project-URL: Homepage, https://github.com/ayder/ayder-cli
 Project-URL: Repository, https://github.com/ayder/ayder-cli.git
@@ -19,14 +19,12 @@ Requires-Dist: google-genai
 Requires-Dist: httpx
 Requires-Dist: libcst>=1.0.0
 Requires-Dist: loguru
-Requires-Dist: ollama>=0.4.0
+Requires-Dist: ollama>=0.6.1
 Requires-Dist: openai
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: textual>=0.50.0
 Requires-Dist: tiktoken>=0.7.0
-Provides-Extra: temporal
-Requires-Dist: temporalio<1.23.0,>=1.22.0; (python_version < '3.13') and extra == 'temporal'
 Description-Content-Type: text/markdown
 
 # ayder-cli
@@ -54,6 +52,7 @@ Most AI coding assistants require cloud APIs, subscriptions, or heavy IDE plugin
 - **7 native drivers** -- Ollama, OpenAI, Anthropic, Gemini, DeepSeek, Qwen (DashScope), and GLM (ZhipuAI). Each driver guarantees native tool calling and streaming support.
 - **Fully local or cloud** -- run locally with Ollama, or connect to any cloud provider.
 - **Agentic workflow** -- the LLM reads files, edits code, runs shell commands, and iterates autonomously with configurable iteration limits per message.
+- **Multi-agent** -- define specialized sub-agents in `config.toml`. Each agent runs independently with its own LLM, model, and context. Results are injected back into the main conversation when complete.
 - **Textual TUI** -- an inline terminal interface with chat view, tool panel, thinking block toggle, slash command auto-completion, permission toggles, and tool confirmation modals with diff previews.
 - **Minimal dependencies** -- OpenAI SDK, Rich, and Textual. Other provider SDKs are optional.
 
@@ -210,6 +209,7 @@ max_output_tokens = 4096      # Max tokens in LLM response
 max_history_messages = 30     # Messages kept in history
 prompt = "STANDARD"           # System prompt tier: MINIMAL, STANDARD, EXTENDED
 tool_tags = ["core", "metadata"]  # Enabled tool tags (see /plugin)
+agent_timeout = 300           # Seconds before a background agent is cancelled
 
 [logging]
 file_enabled = true
@@ -343,22 +343,34 @@ echo "fix the bug" | ayder -r -w -x
 
 ### Context Management
 
-As conversations grow, LLM performance degrades due to context bloat — long tool results, stale history, and repeated context eat into the model's usable window. ayder-cli includes a built-in context manager that solves this automatically. Every message is assigned an importance tier (system > recent user > recent assistant > tool results > old history), and when the conversation approaches the token budget the manager compresses old tool results (JSON outputs are structurally summarized, large text is head/tail truncated) and prunes the lowest-priority messages first. Tool call + tool result pairs are kept as atomic units so the model never sees orphaned results. If `tiktoken` is installed, token counts are exact; otherwise a character-based heuristic is used (~4 chars/token for text, ~3.5 for code).
+ayder-cli includes a context manager that automatically keeps your conversation within the model's token budget. The implementation is **driver-aware** — Ollama gets a specialized KV-cache-optimized manager, while cloud providers (Anthropic, OpenAI, Gemini) use a general-purpose tiered manager.
 
-The context manager is enabled by default and configured under `[context_manager]` in `config.toml`. The defaults work well for most setups, but here are the knobs you can tune:
+**Ollama-specific optimizations** (automatic when `driver = "ollama"`):
+
+- **KV-cache-aware**: Messages are append-only and never reordered. The system prompt is frozen at session start. This preserves Ollama's KV-cache prefix between calls — subsequent prompts process only new tokens instead of recomputing everything.
+- **Real token counts**: Uses Ollama's `prompt_eval_count` and `eval_count` from native API responses instead of estimates. Compaction decisions are based on actual usage, not heuristics.
+- **Cache monitoring**: Tracks `prompt_eval_duration / prompt_eval_count` ratio to detect KV-cache hits (hot/warm/miss). When the cache is hot, compaction is delayed (threshold raised from 70% to 90%) to avoid invalidating it.
+- **Auto-detected context length**: On startup, queries `/api/show` to get the model's real context length instead of relying on `num_ctx`. Falls back to `num_ctx` if detection fails.
+- **Heuristic compaction**: When the context fills up, oldest message units are replaced with a text summary — no LLM call needed.
+- **Native SDK**: Uses `ollama.AsyncClient` directly (not the OpenAI compatibility layer) for full timing data, native thinking support, and `keep_alive=-1` to prevent model unloading.
+
+**General-purpose manager** (Anthropic, OpenAI, Gemini, and other drivers):
+
+Every message is assigned an importance tier (system > recent user > recent assistant > tool results > old history). When the conversation approaches the token budget, old tool results are compressed (JSON structurally summarized, large text head/tail truncated) and the lowest-priority messages are pruned. Tool call + result pairs are kept as atomic units.
+
+The context manager is configured under `[context_manager]` in `config.toml`:
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `enabled` | `true` | Master switch. Set `false` to disable all automatic management. |
-| `max_context_tokens` | `8192` | Total token budget for the conversation. Set this to match your model's context window (e.g., `65536` for qwen3-coder, `200000` for Claude). |
-| `reserve_ratio` | `0.30` | Fraction of the budget reserved for the LLM response. A 30% reserve on 65k tokens means ~45k tokens are available for history. |
-| `summarization_threshold` | `0.70` | When utilization exceeds this ratio, the manager triggers summarization. |
-| `compression_threshold` | `0.50` | When utilization exceeds this ratio, old tool results are compressed. |
+| `enabled` | `true` | Master switch. |
+| `max_context_tokens` | `8192` | Fallback token budget (Ollama auto-detects from model). |
+| `reserve_ratio` | `0.30` | Fraction reserved for the LLM response. |
+| `compaction_threshold` | `0.70` | Utilization ratio that triggers compaction. |
 | `tool_result_compress_age` | `5` | Tool results older than N messages are eligible for compression. |
 | `max_tool_result_length` | `2048` | Maximum character length for a compressed tool result. |
 | `compress_tool_results` | `true` | Enable automatic tool result compression. |
 
-For small local models (7B-14B), lower `max_context_tokens` to match the model's actual window and reduce `reserve_ratio` to `0.20` so more history fits. For large cloud models, increase `max_context_tokens` and raise `summarization_threshold` to `0.80` to delay summarization and let the model use its full reasoning capacity. You can also manually manage context with `/save-memory`, `/load-memory`, and `/compact`.
+You can also manually manage context with `/save-memory`, `/load-memory`, and `/compact`.
 
 ### Slash Commands
 
@@ -383,6 +395,9 @@ For small local models (7B-14B), lower `max_context_tokens` to match the model's
 | `/load-memory` | Load memory and restore context |
 | `/archive-completed-tasks` | Move completed tasks to `.ayder/task_archive/` |
 | `/temporal` | Start/status Temporal queue worker |
+| `/agent list` | List configured agents and their current status |
+| `/agent <name> <task>` | Dispatch an agent to run a task in the background |
+| `/agent cancel <name>` | Cancel a running agent |
 
 ### Logging
 
@@ -488,6 +503,155 @@ The tool system:
 | **Web** | `fetch_web` |
 | **DBS** | `dbs_tool` (RAG API for DBS-related queries) |
 | **Workflow** | `temporal_workflow` |
+| **Agents** | `call_agent` (dispatch a named agent to run a task in the background) |
+
+## Multi-Agent System
+
+ayder-cli supports user-defined **specialized agents**: each agent is an independent AI loop with its own LLM provider, model, system prompt, and context window. Agents run as background tasks — they never block the main conversation and their results are automatically injected back when they complete.
+
+### How Agents Work
+
+```
+Main LLM (your conversation)
+    │
+    ├─ calls `call_agent` tool  ─────────────────────────────────┐
+    │   OR you type `/agent <name> <task>`                       │
+    │                                                            ▼
+    │                                            AgentRunner (background asyncio task)
+    │                                            ┌─────────────────────────────────┐
+    │                                            │  Isolated ChatLoop              │
+    │                                            │  • own LLM provider + model     │
+    │                                            │  • own context window           │
+    │                                            │  • own ToolRegistry             │
+    │                                            │  • auto-approves all tools      │
+    │                                            │  • produces <agent-summary>     │
+    │                                            └────────────────┬────────────────┘
+    │                                                             │ completes
+    │                                                             ▼
+    │                                            AgentSummary → _summary_queue
+    │
+    ▼ (next main LLM turn)
+pre_iteration_hook drains queue
+    └─ injects AgentSummary as system message into main context
+         └─ main LLM sees: "[Agent 'reviewer' completed] FINDINGS: ..."
+```
+
+Key properties:
+- **Separate context** — agents have no access to the main conversation history. They receive only their system prompt and the task description.
+- **Non-blocking** — dispatching an agent returns immediately. Both `/agent` and `call_agent` are fire-and-forget.
+- **Concurrent** — multiple agents can run simultaneously, each in its own async task.
+- **Summary injection** — when an agent finishes, its structured `<agent-summary>` block is injected as a system message into the main LLM's context at the start of the next turn.
+- **Timeout** — agents are automatically cancelled after `agent_timeout` seconds (default: 300).
+
+### Configuring Agents
+
+Add `[agents.<name>]` sections to your `~/.ayder/config.toml`:
+
+```toml
+[app]
+provider = "ollama"
+agent_timeout = 300           # Global timeout for all agents (seconds)
+
+[llm.ollama]
+driver = "ollama"
+model = "qwen3-coder:latest"
+num_ctx = 65536
+
+[llm.anthropic]
+driver = "anthropic"
+api_key = "sk-ant-..."
+model = "claude-sonnet-4-5-20250929"
+num_ctx = 200000
+
+# --- Agents ---
+
+[agents.code-reviewer]
+system_prompt = """You are a senior code reviewer. Review the code for bugs,
+security issues, and style violations. Be concise and actionable."""
+provider = "anthropic"         # Optional: use a different provider than main
+model = "claude-sonnet-4-5-20250929"  # Optional: use a different model
+
+[agents.test-writer]
+system_prompt = """You are a test engineer. Write comprehensive pytest tests
+for the code provided. Follow existing test patterns in the codebase."""
+# No provider/model → inherits from [app] provider
+
+[agents.doc-writer]
+system_prompt = """You are a technical writer. Write clear, concise docstrings
+and inline comments for the code provided."""
+```
+
+Each agent field:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `system_prompt` | Yes | The agent's role and instructions |
+| `provider` | No | LLM provider profile name (inherits from `[app]` if omitted) |
+| `model` | No | Model name override (inherits from provider profile if omitted) |
+
+### Using Agents
+
+**From the TUI (slash commands):**
+
+```
+# List configured agents and their status
+/agent list
+
+# Dispatch an agent to review your authentication module
+/agent code-reviewer Review src/auth.py for security issues
+
+# Dispatch the test writer for a specific module
+/agent test-writer Write tests for src/api/users.py
+
+# Cancel a running agent
+/agent cancel code-reviewer
+```
+
+**Via the main LLM (automatic):**
+
+When agents are configured, the main LLM is told about them via its system prompt and can call `call_agent` autonomously:
+
+```
+You: Review the authentication module and write tests for it.
+
+LLM: I'll dispatch two agents to handle this in parallel.
+     [calls call_agent: name="code-reviewer", task="Review src/auth.py..."]
+     [calls call_agent: name="test-writer", task="Write tests for src/auth.py..."]
+
+     Both agents are running in the background. I'll incorporate
+     their findings when they complete.
+
+... (agents run independently) ...
+
+LLM: [next turn, after agents complete]
+     The code-reviewer found 2 issues: ...
+     The test-writer produced 8 new tests: ...
+```
+
+**Agent summary format:**
+
+Agents end their final response with a structured block that ayder-cli parses:
+
+```
+<agent-summary>
+FINDINGS: Found a SQL injection vulnerability in login() and missing input validation in register()
+FILES_CHANGED: none
+RECOMMENDATIONS: Parameterize all DB queries; add Pydantic validators to all endpoints
+</agent-summary>
+```
+
+This summary is injected into the main LLM's context as a system message so the main agent can act on it, summarize it for you, or chain it to further work.
+
+## Plugins
+
+Official plugins (venv, python, dbs, mcp, temporal) are maintained in the **[ayder/ayder-plugins](https://github.com/ayder/ayder-plugins)** repository. Install any plugin directly from GitHub:
+
+```bash
+ayder install-plugin https://github.com/ayder/ayder-plugins/tree/main/venv-tools
+ayder install-plugin https://github.com/ayder/ayder-plugins/tree/main/python-tools
+```
+
+Plugins can also be hosted in any public GitHub repository — point `install-plugin` at any repo or subdirectory containing a `plugin.toml`.
 
 ## License
 

{ayder_cli-1.0 → ayder_cli-1.6.1}/README.md

@@ -23,6 +23,7 @@ Most AI coding assistants require cloud APIs, subscriptions, or heavy IDE plugin
 - **7 native drivers** -- Ollama, OpenAI, Anthropic, Gemini, DeepSeek, Qwen (DashScope), and GLM (ZhipuAI). Each driver guarantees native tool calling and streaming support.
 - **Fully local or cloud** -- run locally with Ollama, or connect to any cloud provider.
 - **Agentic workflow** -- the LLM reads files, edits code, runs shell commands, and iterates autonomously with configurable iteration limits per message.
+- **Multi-agent** -- define specialized sub-agents in `config.toml`. Each agent runs independently with its own LLM, model, and context. Results are injected back into the main conversation when complete.
 - **Textual TUI** -- an inline terminal interface with chat view, tool panel, thinking block toggle, slash command auto-completion, permission toggles, and tool confirmation modals with diff previews.
 - **Minimal dependencies** -- OpenAI SDK, Rich, and Textual. Other provider SDKs are optional.
 
@@ -179,6 +180,7 @@ max_output_tokens = 4096      # Max tokens in LLM response
 max_history_messages = 30     # Messages kept in history
 prompt = "STANDARD"           # System prompt tier: MINIMAL, STANDARD, EXTENDED
 tool_tags = ["core", "metadata"]  # Enabled tool tags (see /plugin)
+agent_timeout = 300           # Seconds before a background agent is cancelled
 
 [logging]
 file_enabled = true
@@ -312,22 +314,34 @@ echo "fix the bug" | ayder -r -w -x
 
 ### Context Management
 
-As conversations grow, LLM performance degrades due to context bloat — long tool results, stale history, and repeated context eat into the model's usable window. ayder-cli includes a built-in context manager that solves this automatically. Every message is assigned an importance tier (system > recent user > recent assistant > tool results > old history), and when the conversation approaches the token budget the manager compresses old tool results (JSON outputs are structurally summarized, large text is head/tail truncated) and prunes the lowest-priority messages first. Tool call + tool result pairs are kept as atomic units so the model never sees orphaned results. If `tiktoken` is installed, token counts are exact; otherwise a character-based heuristic is used (~4 chars/token for text, ~3.5 for code).
+ayder-cli includes a context manager that automatically keeps your conversation within the model's token budget. The implementation is **driver-aware** — Ollama gets a specialized KV-cache-optimized manager, while cloud providers (Anthropic, OpenAI, Gemini) use a general-purpose tiered manager.
 
-The context manager is enabled by default and configured under `[context_manager]` in `config.toml`. The defaults work well for most setups, but here are the knobs you can tune:
+**Ollama-specific optimizations** (automatic when `driver = "ollama"`):
+
+- **KV-cache-aware**: Messages are append-only and never reordered. The system prompt is frozen at session start. This preserves Ollama's KV-cache prefix between calls — subsequent prompts process only new tokens instead of recomputing everything.
+- **Real token counts**: Uses Ollama's `prompt_eval_count` and `eval_count` from native API responses instead of estimates. Compaction decisions are based on actual usage, not heuristics.
+- **Cache monitoring**: Tracks `prompt_eval_duration / prompt_eval_count` ratio to detect KV-cache hits (hot/warm/miss). When the cache is hot, compaction is delayed (threshold raised from 70% to 90%) to avoid invalidating it.
+- **Auto-detected context length**: On startup, queries `/api/show` to get the model's real context length instead of relying on `num_ctx`. Falls back to `num_ctx` if detection fails.
+- **Heuristic compaction**: When the context fills up, oldest message units are replaced with a text summary — no LLM call needed.
+- **Native SDK**: Uses `ollama.AsyncClient` directly (not the OpenAI compatibility layer) for full timing data, native thinking support, and `keep_alive=-1` to prevent model unloading.
+
+**General-purpose manager** (Anthropic, OpenAI, Gemini, and other drivers):
+
+Every message is assigned an importance tier (system > recent user > recent assistant > tool results > old history). When the conversation approaches the token budget, old tool results are compressed (JSON structurally summarized, large text head/tail truncated) and the lowest-priority messages are pruned. Tool call + result pairs are kept as atomic units.
+
+The context manager is configured under `[context_manager]` in `config.toml`:
 
 | Setting | Default | Description |
 |---------|---------|-------------|
-| `enabled` | `true` | Master switch. Set `false` to disable all automatic management. |
-| `max_context_tokens` | `8192` | Total token budget for the conversation. Set this to match your model's context window (e.g., `65536` for qwen3-coder, `200000` for Claude). |
-| `reserve_ratio` | `0.30` | Fraction of the budget reserved for the LLM response. A 30% reserve on 65k tokens means ~45k tokens are available for history. |
-| `summarization_threshold` | `0.70` | When utilization exceeds this ratio, the manager triggers summarization. |
-| `compression_threshold` | `0.50` | When utilization exceeds this ratio, old tool results are compressed. |
+| `enabled` | `true` | Master switch. |
+| `max_context_tokens` | `8192` | Fallback token budget (Ollama auto-detects from model). |
+| `reserve_ratio` | `0.30` | Fraction reserved for the LLM response. |
+| `compaction_threshold` | `0.70` | Utilization ratio that triggers compaction. |
 | `tool_result_compress_age` | `5` | Tool results older than N messages are eligible for compression. |
 | `max_tool_result_length` | `2048` | Maximum character length for a compressed tool result. |
 | `compress_tool_results` | `true` | Enable automatic tool result compression. |
 
-For small local models (7B-14B), lower `max_context_tokens` to match the model's actual window and reduce `reserve_ratio` to `0.20` so more history fits. For large cloud models, increase `max_context_tokens` and raise `summarization_threshold` to `0.80` to delay summarization and let the model use its full reasoning capacity. You can also manually manage context with `/save-memory`, `/load-memory`, and `/compact`.
+You can also manually manage context with `/save-memory`, `/load-memory`, and `/compact`.
 
 ### Slash Commands
 
@@ -352,6 +366,9 @@ For small local models (7B-14B), lower `max_context_tokens` to match the model's
 | `/load-memory` | Load memory and restore context |
 | `/archive-completed-tasks` | Move completed tasks to `.ayder/task_archive/` |
 | `/temporal` | Start/status Temporal queue worker |
+| `/agent list` | List configured agents and their current status |
+| `/agent <name> <task>` | Dispatch an agent to run a task in the background |
+| `/agent cancel <name>` | Cancel a running agent |
 
 ### Logging
 
@@ -457,6 +474,155 @@ The tool system:
 | **Web** | `fetch_web` |
 | **DBS** | `dbs_tool` (RAG API for DBS-related queries) |
 | **Workflow** | `temporal_workflow` |
+| **Agents** | `call_agent` (dispatch a named agent to run a task in the background) |
+
+## Multi-Agent System
+
+ayder-cli supports user-defined **specialized agents**: each agent is an independent AI loop with its own LLM provider, model, system prompt, and context window. Agents run as background tasks — they never block the main conversation and their results are automatically injected back when they complete.
+
+### How Agents Work
+
+```
+Main LLM (your conversation)
+    │
+    ├─ calls `call_agent` tool  ─────────────────────────────────┐
+    │   OR you type `/agent <name> <task>`                       │
+    │                                                            ▼
+    │                                            AgentRunner (background asyncio task)
+    │                                            ┌─────────────────────────────────┐
+    │                                            │  Isolated ChatLoop              │
+    │                                            │  • own LLM provider + model     │
+    │                                            │  • own context window           │
+    │                                            │  • own ToolRegistry             │
+    │                                            │  • auto-approves all tools      │
+    │                                            │  • produces <agent-summary>     │
+    │                                            └────────────────┬────────────────┘
+    │                                                             │ completes
+    │                                                             ▼
+    │                                            AgentSummary → _summary_queue
+    │
+    ▼ (next main LLM turn)
+pre_iteration_hook drains queue
+    └─ injects AgentSummary as system message into main context
+         └─ main LLM sees: "[Agent 'reviewer' completed] FINDINGS: ..."
+```
+
+Key properties:
+- **Separate context** — agents have no access to the main conversation history. They receive only their system prompt and the task description.
+- **Non-blocking** — dispatching an agent returns immediately. Both `/agent` and `call_agent` are fire-and-forget.
+- **Concurrent** — multiple agents can run simultaneously, each in its own async task.
+- **Summary injection** — when an agent finishes, its structured `<agent-summary>` block is injected as a system message into the main LLM's context at the start of the next turn.
+- **Timeout** — agents are automatically cancelled after `agent_timeout` seconds (default: 300).
+
+### Configuring Agents
+
+Add `[agents.<name>]` sections to your `~/.ayder/config.toml`:
+
+```toml
+[app]
+provider = "ollama"
+agent_timeout = 300           # Global timeout for all agents (seconds)
+
+[llm.ollama]
+driver = "ollama"
+model = "qwen3-coder:latest"
+num_ctx = 65536
+
+[llm.anthropic]
+driver = "anthropic"
+api_key = "sk-ant-..."
+model = "claude-sonnet-4-5-20250929"
+num_ctx = 200000
+
+# --- Agents ---
+
+[agents.code-reviewer]
+system_prompt = """You are a senior code reviewer. Review the code for bugs,
+security issues, and style violations. Be concise and actionable."""
+provider = "anthropic"         # Optional: use a different provider than main
+model = "claude-sonnet-4-5-20250929"  # Optional: use a different model
+
+[agents.test-writer]
+system_prompt = """You are a test engineer. Write comprehensive pytest tests
+for the code provided. Follow existing test patterns in the codebase."""
+# No provider/model → inherits from [app] provider
+
+[agents.doc-writer]
+system_prompt = """You are a technical writer. Write clear, concise docstrings
+and inline comments for the code provided."""
+```
+
+Each agent field:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `system_prompt` | Yes | The agent's role and instructions |
+| `provider` | No | LLM provider profile name (inherits from `[app]` if omitted) |
+| `model` | No | Model name override (inherits from provider profile if omitted) |
+
+### Using Agents
+
+**From the TUI (slash commands):**
+
+```
+# List configured agents and their status
+/agent list
+
+# Dispatch an agent to review your authentication module
+/agent code-reviewer Review src/auth.py for security issues
+
+# Dispatch the test writer for a specific module
+/agent test-writer Write tests for src/api/users.py
+
+# Cancel a running agent
+/agent cancel code-reviewer
+```
+
+**Via the main LLM (automatic):**
+
+When agents are configured, the main LLM is told about them via its system prompt and can call `call_agent` autonomously:
+
+```
+You: Review the authentication module and write tests for it.
+
+LLM: I'll dispatch two agents to handle this in parallel.
+     [calls call_agent: name="code-reviewer", task="Review src/auth.py..."]
+     [calls call_agent: name="test-writer", task="Write tests for src/auth.py..."]
+
+     Both agents are running in the background. I'll incorporate
+     their findings when they complete.
+
+... (agents run independently) ...
+
+LLM: [next turn, after agents complete]
+     The code-reviewer found 2 issues: ...
+     The test-writer produced 8 new tests: ...
+```
+
+**Agent summary format:**
+
+Agents end their final response with a structured block that ayder-cli parses:
+
+```
+<agent-summary>
+FINDINGS: Found a SQL injection vulnerability in login() and missing input validation in register()
+FILES_CHANGED: none
+RECOMMENDATIONS: Parameterize all DB queries; add Pydantic validators to all endpoints
+</agent-summary>
+```
+
+This summary is injected into the main LLM's context as a system message so the main agent can act on it, summarize it for you, or chain it to further work.
+
+## Plugins
+
+Official plugins (venv, python, dbs, mcp, temporal) are maintained in the **[ayder/ayder-plugins](https://github.com/ayder/ayder-plugins)** repository. Install any plugin directly from GitHub:
+
+```bash
+ayder install-plugin https://github.com/ayder/ayder-plugins/tree/main/venv-tools
+ayder install-plugin https://github.com/ayder/ayder-plugins/tree/main/python-tools
+```
+
+Plugins can also be hosted in any public GitHub repository — point `install-plugin` at any repo or subdirectory containing a `plugin.toml`.
 
 ## License