Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 semantic-release-bot
|
992e60980c | ||
|
asepharyana
|
74b1ad4302 | ||
|
semantic-release-bot
|
9ad04cf819 | ||
|
asepharyana
|
b46935c606 | ||
|
asepharyana
|
b28a5fe384 | ||
|
semantic-release-bot
|
b66898ea28 | ||
|
asepharyana
|
9aca45cb65 | ||
|
semantic-release-bot
|
4dccf0cee4 | ||
|
asepharyana
|
1f91b44708 | ||
|
semantic-release-bot
|
b25929824a | ||
|
asepharyana
|
3fd9a2b2db | ||
|
asepharyana
|
6a98d52d54 | ||
|
semantic-release-bot
|
3847c0e6fd | ||
|
asepharyana
|
5023e5dfa1 | ||
|
asepharyana
|
eac0443c4c | ||
|
asepharyana
|
14f3eae62a |
@@ -7,3 +7,4 @@ package-lock.json
|
||||
.superpowers/
|
||||
docs/lesson/
|
||||
.kilo/
|
||||
.hermes/
|
||||
@@ -1,3 +1,46 @@
|
||||
## [1.19.6](https://github.com/asepharyana/zesdex/compare/v1.19.5...v1.19.6) (2026-08-27)
|
||||
|
||||
|
||||
### Performance Improvements
|
||||
|
||||
* **agent:** eksekusi tool read-only paralel seperti Claude Code ([74b1ad4](https://github.com/asepharyana/zesdex/commit/74b1ad43020a11ca27e60e3a24de0db5d1ab37b4))
|
||||
|
||||
## [1.19.5](https://github.com/asepharyana/zesdex/compare/v1.19.4...v1.19.5) (2026-08-27)
|
||||
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* **api:** model Opus default pakai claude-opus-5 (bukan -4-8) ([b28a5fe](https://github.com/asepharyana/zesdex/commit/b28a5fe384fd45255a6b249c7febd3b4ffc0fd2f))
|
||||
* **api:** update zesdex packages to version 1.19.4 ([b46935c](https://github.com/asepharyana/zesdex/commit/b46935c606d4f68ea227c7db27e4c2aa9b4e373c))
|
||||
|
||||
## [1.19.4](https://github.com/asepharyana/zesdex/compare/v1.19.3...v1.19.4) (2026-08-27)
|
||||
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* **api:** model claude selalu pakai Opus dari settings.json, bukan deepseek ([9aca45c](https://github.com/asepharyana/zesdex/commit/9aca45cb65d6913d14fecc10d70c180934f69d74))
|
||||
|
||||
## [1.19.3](https://github.com/asepharyana/zesdex/compare/v1.19.2...v1.19.3) (2026-08-27)
|
||||
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
* **api:** model Opus pakai URL + API custom dari ~/.claude/settings.json ([1f91b44](https://github.com/asepharyana/zesdex/commit/1f91b447080e7106201d77585edb7d38b74e34bb))
|
||||
|
||||
## [1.19.2](https://github.com/asepharyana/zesdex/compare/v1.19.1...v1.19.2) (2026-08-27)
|
||||
|
||||
|
||||
### Performance Improvements
|
||||
|
||||
* **agent:** stabilkan async & parallel — satu runtime, bounded concurrency, isolasi error ([6a98d52](https://github.com/asepharyana/zesdex/commit/6a98d52d54a69f78710d852a69dda3ac0a4ead31))
|
||||
|
||||
## [1.19.1](https://github.com/asepharyana/zesdex/compare/v1.19.0...v1.19.1) (2026-08-27)
|
||||
|
||||
|
||||
### Performance Improvements
|
||||
|
||||
* **agent:** rombak alur AI agent — adaptif, hemat token, self-healing ([eac0443](https://github.com/asepharyana/zesdex/commit/eac0443c4c3b8bfcbefd4bad9554168fb6525b94))
|
||||
|
||||
# [1.19.0](https://github.com/asepharyana/zesdex/compare/v1.18.4...v1.19.0) (2026-08-27)
|
||||
|
||||
|
||||
|
||||
Generated
+12
-11
@@ -4862,7 +4862,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-api"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"argon2",
|
||||
@@ -4885,11 +4885,12 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-application"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"base64",
|
||||
"chrono",
|
||||
"futures-util",
|
||||
"serde",
|
||||
"serde_json",
|
||||
"sha2 0.11.0",
|
||||
@@ -4902,7 +4903,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-bootstrap"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"chrono",
|
||||
@@ -4919,7 +4920,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-daemon"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"base64",
|
||||
@@ -4943,7 +4944,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-domain"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"base64",
|
||||
@@ -4959,7 +4960,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-gateway"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"axum",
|
||||
@@ -4986,7 +4987,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-grpc"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"axum",
|
||||
@@ -5003,7 +5004,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-infrastructure"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"argon2",
|
||||
@@ -5051,7 +5052,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-tui"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"base64",
|
||||
@@ -5077,7 +5078,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-web"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"axum",
|
||||
@@ -5097,7 +5098,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "zesdex-ws"
|
||||
version = "1.18.3"
|
||||
version = "1.19.4"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"axum",
|
||||
|
||||
+1
-1
@@ -15,7 +15,7 @@ members = [
|
||||
]
|
||||
|
||||
[workspace.package]
|
||||
version = "1.19.0"
|
||||
version = "1.19.6"
|
||||
edition = "2021"
|
||||
authors = ["asepharyana <superaseph@gmail.com>"]
|
||||
|
||||
|
||||
@@ -1,250 +0,0 @@
|
||||
# Zesdex — Autonomous AI Coding Agent
|
||||
|
||||
Zesdex is an autonomous AI coding agent with a Terminal UI (TUI). It acts as an
|
||||
OpenAI/Anthropic-compatible LLM client wrapped in a tool-use harness with **37
|
||||
built-in tools** — file operations, git, shell execution, LSP integration, MCP,
|
||||
subagent orchestration, and more.
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ Mode Selector │
|
||||
│ TUI (default) ─── Daemon ─── Attach ─── API ─── WS/gRPC/Web │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Run the TUI (default mode)
|
||||
cargo run
|
||||
|
||||
# Run the REST API server
|
||||
cargo run -- --api --api-port 8080
|
||||
|
||||
# Run in daemon mode (background + IPC)
|
||||
cargo run -- --daemon
|
||||
|
||||
# Attach TUI to a running daemon session
|
||||
cargo run -- --attach <session-id>
|
||||
|
||||
# Seed initial data (first run)
|
||||
cargo run --bin bootstrap
|
||||
```
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- **Rust** 1.81+ (edition 2021)
|
||||
- **Linux** or **macOS** (Unix domain sockets required for daemon mode)
|
||||
- An **API key** for an OpenAI/Anthropic-compatible LLM provider (set via
|
||||
settings or environment variable)
|
||||
|
||||
---
|
||||
|
||||
## Modes
|
||||
|
||||
| Flag | Mode | Description |
|
||||
|------|------|-------------|
|
||||
| *(none)* | **TUI** | Full terminal UI with chat, overlays, and agent loop in one process |
|
||||
| `--daemon` | **Daemon** | Background daemon with IPC socket; clients attach separately |
|
||||
| `--attach <id>` | **Attach** | Connect TUI to an existing daemon session via Unix socket |
|
||||
| `--api` | **REST API** | HTTP server with session management and chat endpoints |
|
||||
| `--ws` | **WebSocket** | WebSocket server for real-time communication |
|
||||
| `--grpc` | **gRPC** | gRPC server for programmatic access |
|
||||
| `--web` | **Web** | Serves the web frontend |
|
||||
| `--api-port`, `--ws-port`, `--grpc-port`, `--web-port` | *(ports)* | Configure server ports (defaults: 8080, 8081, 50051, 3000) |
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Clean Architecture Layering
|
||||
|
||||
```
|
||||
apps/
|
||||
├── domain/ # Pure entities, value objects, repository/service traits
|
||||
│ # Zero framework deps — only serde + chrono + uuid
|
||||
├── application/ # Use-case services (auth, sessions, conversations, memory)
|
||||
│ # Depends only on domain-layer trait interfaces
|
||||
├── infrastructure/ # All I/O: LLM client, IPC, persistence, LSP, MCP, tools
|
||||
│ # Implements domain/application port interfaces
|
||||
└── interfaces/ # Entry points
|
||||
├── tui/ # Ratatui terminal UI
|
||||
├── api/ # Axum REST API
|
||||
├── daemon/ # Unix socket daemon + client
|
||||
├── ws/ # WebSocket server
|
||||
├── grpc/ # gRPC server
|
||||
└── web/ # Web frontend (static file server)
|
||||
```
|
||||
|
||||
### Tool System
|
||||
|
||||
37 tools across 9 categories:
|
||||
|
||||
| Category | Tools |
|
||||
|----------|-------|
|
||||
| **File System** | `read`, `write`, `edit`, `delete`, `dir_list`, `dir_cache_update` |
|
||||
| **Shell** | `bash`, `bash_interactive`, `bash_kill`, `bash_output` |
|
||||
| **Git** | `git_operator`, `git_cred`, `git_worktree` |
|
||||
| **Search** | `search`, `grep`, `glob`, `semantic_search` |
|
||||
| **LSP** | `lsp_connect`, `lsp_hover`, `lsp_completion`, `lsp_definition`, `lsp_references`, `lsp_diagnostics`, `lsp_disconnect` |
|
||||
| **Memory** | `remember`, `recall`, `forget` |
|
||||
| **Workflow** | `spawn_agents`, `spawn_pipeline`, `plan`, `sequential_think`, `hive_mind` |
|
||||
| **Utility** | `todo_write`, `todo_finish`, `pong`, `cd` |
|
||||
| **Background** | Background bash jobs with `cancel/status/list` |
|
||||
|
||||
Each tool implements the `Tool` trait:
|
||||
```rust
|
||||
pub trait Tool: Send + Sync {
|
||||
fn name(&self) -> &'static str;
|
||||
fn description(&self) -> &'static str;
|
||||
fn parameters(&self) -> Value;
|
||||
fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String>;
|
||||
}
|
||||
```
|
||||
|
||||
### Hive Mind Orchestration
|
||||
|
||||
The multi-agent orchestration system compiles a **cognitive cycle plan** per
|
||||
task — ordered cycles of parallel processing nodes. Each node has a directive
|
||||
and an **access tier** (`read` / `write` / `full`). Node outputs merge into a
|
||||
shared collective state in real time, and a final **consensus synthesis**
|
||||
produces the unified result.
|
||||
|
||||
- **Auto-trigger**: Complex requests automatically use the hive mind
|
||||
- **Manual entry**: The `hive_mind` tool lets the LLM specify cycles explicitly
|
||||
- **Live progress**: TUI panel shows each node's status and current tool
|
||||
- **Guaranteed docs**: Every convergence writes to `docs/runs/`
|
||||
|
||||
### IPC Protocol (Daemon Mode)
|
||||
|
||||
```
|
||||
┌──────────┐ Unix socket ┌──────────┐
|
||||
│ Client │ ◄──────────────► │ Daemon │
|
||||
│ (TUI) │ length-prefixed│ │
|
||||
└──────────┘ serde_json └──────────┘
|
||||
|
||||
Frame format: [4-byte BE length][JSON payload]
|
||||
```
|
||||
|
||||
The daemon holds `AppStateRest` and drives the agent loop. Clients are stateless
|
||||
renderers that receive full state snapshots after each action.
|
||||
|
||||
---
|
||||
|
||||
## Built-in Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **LLM Provider** | OpenAI/Anthropic-compatible API (streaming + non-streaming) with automatic retry and fallback |
|
||||
| **Tool Harness** | Safety-gated tool execution with graduated review checks |
|
||||
| **Subagents** | Auto-inline review, background test-gen, arch-review, security-review |
|
||||
| **OAuth 2.0** | PKCE flow for LLM provider authentication |
|
||||
| **MCP** | Model Context Protocol server management (stdio + HTTP transport) |
|
||||
| **LSP** | Language Server Protocol integration (completion, hover, diagnostics, references) |
|
||||
| **Session Mgmt** | SQLite-persisted sessions with lock-based concurrency control |
|
||||
| **Memory** | File-based memory system with frontmatter metadata |
|
||||
| **Edit Log** | Append-only edit history with configurable retention |
|
||||
| **Rate Limiting** | Sliding-window per-client rate limiter |
|
||||
| **JWT Auth** | HS256 JWT access/refresh tokens (API mode) |
|
||||
| **Password Auth** | Argon2 password hashing with pepper |
|
||||
| **OAuth Loopback** | Localhost HTTP server for OAuth redirect capture |
|
||||
| **Background Jobs** | Long-running shell jobs with cancellation and output collection |
|
||||
| **Settings** | JSON-persisted settings with hot-reload |
|
||||
|
||||
---
|
||||
|
||||
## TUI Overlays
|
||||
|
||||
16 overlays accessible from the terminal UI:
|
||||
|
||||
| Overlay | Purpose |
|
||||
|---------|---------|
|
||||
| Chat Input | Main input bar with autocomplete |
|
||||
| Bash Panel | Interactive shell panel |
|
||||
| File Editor | Built-in file editor |
|
||||
| Effort Selector | LLM reasoning effort selector |
|
||||
| Help | Keybindings reference |
|
||||
| Key Input | Custom key binding configuration |
|
||||
| Learning | Lesson viewer |
|
||||
| Loading | Generating spinner |
|
||||
| MCP Manager | MCP server management |
|
||||
| Model Selector | LLM model picker |
|
||||
| Quit Confirm | Exit confirmation dialog |
|
||||
| Rewind | Message/history rewind |
|
||||
| Settings | Settings panel |
|
||||
| Todo | Task/TODO list |
|
||||
| Usage | Token usage statistics |
|
||||
| Workflow | Hive-mind node progress |
|
||||
|
||||
---
|
||||
|
||||
## Data & Persistence
|
||||
|
||||
All data lives under the platform's data directory (`~/.local/share/zesdex/`):
|
||||
|
||||
```
|
||||
~/.local/share/zesdex/
|
||||
├── settings.json # User settings (provider, model, keys)
|
||||
├── app_config.json # Provider definitions (endpoints, env vars)
|
||||
├── sessions/ # Chat sessions (one subdirectory per session)
|
||||
│ └── <uuid>/
|
||||
│ ├── session.json # Session metadata
|
||||
│ ├── messages.jsonl # Message log
|
||||
│ └── .lock # Session lock file
|
||||
└── memories/ # Memory files with frontmatter metadata
|
||||
└── *.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Build all crates
|
||||
cargo build
|
||||
|
||||
# Run all unit tests (8 tests across 11 crates)
|
||||
cargo test
|
||||
|
||||
# Run clippy linting
|
||||
cargo clippy --all-targets
|
||||
|
||||
# Run with verbose logging
|
||||
RUST_LOG=debug cargo run
|
||||
```
|
||||
|
||||
### Workspace Crates
|
||||
|
||||
| Crate | Path | Layer |
|
||||
|-------|------|-------|
|
||||
| `zesdex-domain` | `apps/domain/` | Pure domain entities & traits |
|
||||
| `zesdex-application` | `apps/application/` | Use-case services |
|
||||
| `zesdex-infrastructure` | `apps/infrastructure/` | All I/O & tool implementations |
|
||||
| `zesdex-tui` | `apps/interfaces/tui/` | Ratatui terminal interface |
|
||||
| `zesdex-api` | `apps/interfaces/api/` | Axum REST API |
|
||||
| `zesdex-daemon` | `apps/interfaces/daemon/` | Unix socket daemon |
|
||||
| `zesdex-ws` | `apps/interfaces/ws/` | WebSocket server |
|
||||
| `zesdex-grpc` | `apps/interfaces/grpc/` | gRPC server |
|
||||
| `zesdex-web` | `apps/interfaces/web/` | Web frontend |
|
||||
| `zesdex-gateway` | `apps/gateway/` | CLI entry point & dispatcher |
|
||||
| `zesdex-bootstrap` | `apps/bootstrap/` | Initial data seeder |
|
||||
|
||||
### Code Map
|
||||
|
||||
Detailed architecture documentation is in `docs/CODEMAPS/`:
|
||||
|
||||
| File | Covers |
|
||||
|------|--------|
|
||||
| `docs/CODEMAPS/architecture.md` | System layout, process modes, data flow |
|
||||
| `docs/CODEMAPS/backend.md` | Provider, OAuth, IPC, workflow engine, MCP, LSP, review |
|
||||
| `docs/CODEMAPS/frontend.md` | TUI render pipeline, 16 overlays, toasts, input handling |
|
||||
| `docs/CODEMAPS/data.md` | Persistence, SQLite msglog, memory files, settings/config |
|
||||
| `docs/CODEMAPS/dependencies.md` | All Rust crates and external services |
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
See `CHANGELOG.md` for release history.
|
||||
@@ -16,6 +16,7 @@ uuid.workspace = true
|
||||
anyhow.workspace = true
|
||||
tracing.workspace = true
|
||||
tokio.workspace = true
|
||||
futures-util.workspace = true
|
||||
base64.workspace = true
|
||||
sha2.workspace = true
|
||||
url.workspace = true
|
||||
|
||||
@@ -1,57 +0,0 @@
|
||||
//! Mandatory explore phase — spawns parallel subagents to discover context
|
||||
//! before the main agent begins its turn.
|
||||
//!
|
||||
//! # Flow
|
||||
//!
|
||||
//! Before the main agent's LLM loop, [`ExploreService::explore`] dispatches
|
||||
//! at least 3 subagents in parallel (code-structure scan, symbol-index query,
|
||||
//! semantic-context search). Their findings are consolidated into a single
|
||||
//! system message that is prepended to the conversation.
|
||||
//!
|
||||
//! # Why mandatory
|
||||
//!
|
||||
//! Without structured exploration the main agent works from an empty context
|
||||
//! window. The explore phase guarantees that every turn starts with a compact
|
||||
//! snapshot of what the codebase contains and where relevant code lives.
|
||||
|
||||
use anyhow::Result;
|
||||
use std::collections::VecDeque;
|
||||
use std::future::Future;
|
||||
use std::pin::Pin;
|
||||
use std::sync::{Arc, Mutex};
|
||||
use zesdex_domain::agent::TurnEvent;
|
||||
|
||||
/// The consolidated output of an explore phase — a set of system-level
|
||||
/// context messages injected before the main agent prompt.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ExploreOutput {
|
||||
/// One or more system messages summarising what the explore subagents
|
||||
/// discovered. Prepended to the conversation by the turn service.
|
||||
pub context_messages: Vec<String>,
|
||||
/// Short human-readable summary of what was explored.
|
||||
pub summary: String,
|
||||
}
|
||||
|
||||
/// Service trait for the mandatory pre-turn exploration phase.
|
||||
///
|
||||
/// Implementors spawn ≥3 parallel subagents, each analysing a different
|
||||
/// aspect of the workspace, and return a consolidated summary.
|
||||
///
|
||||
/// # Object safety
|
||||
///
|
||||
/// This trait is `dyn`-safe — it returns `Pin<Box<dyn Future>>` so it can
|
||||
/// be stored as `Arc<dyn ExploreService>`.
|
||||
pub trait ExploreService: Send + Sync {
|
||||
/// Run the explore phase.
|
||||
///
|
||||
/// `query` — the user's current input phrase.
|
||||
/// `workspace_root` — absolute path to the workspace root.
|
||||
/// `turn_events` — shared event queue for TUI updates.
|
||||
/// Returns structured context messages and a summary blob.
|
||||
fn explore<'a>(
|
||||
&'a self,
|
||||
query: &'a str,
|
||||
workspace_root: &'a str,
|
||||
turn_events: &'a Arc<Mutex<VecDeque<TurnEvent>>>,
|
||||
) -> Pin<Box<dyn Future<Output = Result<ExploreOutput>> + Send + 'a>>;
|
||||
}
|
||||
@@ -11,6 +11,17 @@ pub trait ToolExecutor: Send + Sync {
|
||||
tool_name: &str,
|
||||
args: &serde_json::Value,
|
||||
) -> impl Future<Output = Result<String>> + Send;
|
||||
|
||||
/// Whether a tool is *read-only* and therefore safe to run concurrently
|
||||
/// with other read-only tools in the same assistant message.
|
||||
///
|
||||
/// Defaults to `false` (sequential) so a caller that does not know the
|
||||
/// tool surface stays conservative. Concrete executors that know their
|
||||
/// tools override this — e.g. return `true` for `read`/`grep`/`glob`.
|
||||
fn is_parallel_safe(&self, tool_name: &str) -> bool {
|
||||
let _ = tool_name;
|
||||
false
|
||||
}
|
||||
}
|
||||
|
||||
/// Service for running agent turns asynchronously.
|
||||
@@ -19,8 +30,6 @@ pub trait AgentTurnService: Send + Sync {
|
||||
fn run_turn(&self, params: AgentTurnParams) -> impl Future<Output = Result<()>> + Send;
|
||||
}
|
||||
|
||||
pub mod explore;
|
||||
pub mod turn_service;
|
||||
|
||||
pub use explore::{ExploreOutput, ExploreService};
|
||||
pub use turn_service::{compact_messages_with_ai, AgentTurnServiceImpl};
|
||||
|
||||
@@ -7,12 +7,29 @@ use zesdex_domain::agent::{AgentTurnParams, TurnEvent};
|
||||
use zesdex_domain::core::{ChatMessage, StreamEvent, ToolDef};
|
||||
use zesdex_domain::main_agent_prompt;
|
||||
|
||||
use super::{ExploreService, ToolExecutor};
|
||||
use super::ToolExecutor;
|
||||
use crate::ports::ProviderService;
|
||||
|
||||
/// Maximum tool-call iterations per agent turn before forcing termination.
|
||||
const MAX_TURN_ITERATIONS: u32 = 50;
|
||||
|
||||
/// Maximum number of consecutive identical tool errors before the loop
|
||||
/// injects a recovery note and forces a different approach.
|
||||
const MAX_CONSECUTIVE_TOOL_ERRORS: usize = 3;
|
||||
|
||||
/// Total tool-call errors tolerated per turn before the loop is stopped.
|
||||
const MAX_TOTAL_TOOL_ERRORS: usize = 8;
|
||||
|
||||
/// Ceiling for a single tool-result message inserted into context.
|
||||
///
|
||||
/// Tool outputs can be huge (read / semantic_search). Truncating keeps the
|
||||
/// context window from exploding while preserving the important head.
|
||||
const TOOL_OUTPUT_MAX_CHARS: usize = 12_000;
|
||||
|
||||
/// Total conversation characters that trigger auto-compaction before the
|
||||
/// next LLM call.
|
||||
const AUTO_COMPACT_CHARS: usize = 60_000;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helper: push a TurnEvent onto the shared queue.
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -51,6 +68,89 @@ fn make_stream_callback(
|
||||
})
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helper: truncate a long tool output before it enters the conversation
|
||||
// context. Preserves the head and appends a clear truncation marker.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
fn truncate_tool_output(output: String) -> String {
|
||||
if output.len() <= TOOL_OUTPUT_MAX_CHARS {
|
||||
return output;
|
||||
}
|
||||
let mut result: String = output.chars().take(TOOL_OUTPUT_MAX_CHARS).collect();
|
||||
result.push_str(&format!(
|
||||
"\n...[truncated {} chars]",
|
||||
output.len() - TOOL_OUTPUT_MAX_CHARS
|
||||
));
|
||||
result
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helper: adaptive generation parameters.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Pick a `max_tokens` budget for the turn's next LLM call based on the
|
||||
/// length of the user's request. Short requests need far fewer tokens than
|
||||
/// the current hardcoded 4096 — big savings on small tasks.
|
||||
fn adaptive_max_tokens(request_len: usize) -> u32 {
|
||||
if request_len <= 80 {
|
||||
800
|
||||
} else if request_len <= 400 {
|
||||
1600
|
||||
} else {
|
||||
4096
|
||||
}
|
||||
}
|
||||
|
||||
/// Sum the character length of the conversation (user + assistant +
|
||||
/// tool content) as a cheap proxy for context size.
|
||||
fn conversation_chars(messages: &[ChatMessage]) -> usize {
|
||||
messages
|
||||
.iter()
|
||||
.map(|m| m.content.as_deref().map(str::len).unwrap_or(0))
|
||||
.sum()
|
||||
}
|
||||
|
||||
/// Track repeated tool-call errors so the loop can recover instead of
|
||||
/// burning iterations retrying the same failing tool.
|
||||
#[derive(Default)]
|
||||
struct ErrorTracker {
|
||||
consecutive: usize,
|
||||
total: usize,
|
||||
last_tool: String,
|
||||
last_error: String,
|
||||
}
|
||||
|
||||
impl ErrorTracker {
|
||||
fn record(&mut self, tool_name: &str, error: &str, messages: &mut Vec<ChatMessage>) {
|
||||
if self.last_tool == tool_name {
|
||||
self.consecutive += 1;
|
||||
} else {
|
||||
self.consecutive = 1;
|
||||
}
|
||||
self.last_tool = tool_name.to_string();
|
||||
self.last_error = error.to_string();
|
||||
self.total += 1;
|
||||
|
||||
// Inject a recovery note once the same tool keeps failing.
|
||||
if self.consecutive >= MAX_CONSECUTIVE_TOOL_ERRORS
|
||||
&& !messages.iter().any(|m| {
|
||||
m.content
|
||||
.as_deref()
|
||||
.is_some_and(|c| c.contains("[System note]"))
|
||||
})
|
||||
{
|
||||
messages.push(ChatMessage::system(
|
||||
zesdex_domain::agent::prompt::error_recovery_note(tool_name, error),
|
||||
));
|
||||
}
|
||||
}
|
||||
|
||||
fn should_stop(&self) -> bool {
|
||||
self.consecutive >= MAX_CONSECUTIVE_TOOL_ERRORS * 2 || self.total >= MAX_TOTAL_TOOL_ERRORS
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helper: execute a single tool call, push events, return the result string.
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -71,6 +171,7 @@ async fn execute_tool_call<T: ToolExecutor>(
|
||||
};
|
||||
|
||||
let is_error = output.starts_with("Error:");
|
||||
let output = truncate_tool_output(output);
|
||||
|
||||
push_event(
|
||||
turn_events,
|
||||
@@ -86,6 +187,53 @@ async fn execute_tool_call<T: ToolExecutor>(
|
||||
output
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helper: bounded-parallel execution of read-only tool calls.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Maximum number of read-only tool calls executed concurrently in a single
|
||||
/// assistant batch. Models rarely emit more than a handful of reads per
|
||||
/// message; this cap keeps resource usage bounded while still removing the
|
||||
/// serial round-trip latency of many independent lookups.
|
||||
const MAX_PARALLEL_TOOLS: usize = 8;
|
||||
|
||||
fn tool_executor_ref<T: ToolExecutor>(tool_executor: &T) -> &T {
|
||||
tool_executor
|
||||
}
|
||||
|
||||
/// Execute a batch of *read-only* tool calls concurrently (bounded by
|
||||
/// [`MAX_PARALLEL_TOOLS`]) and return their outputs **in the original call
|
||||
/// order**.
|
||||
///
|
||||
/// Order preservation matters: OpenAI/Anthropic tool-calling contracts expect
|
||||
/// tool-result messages to appear in the same order as the `tool_calls`
|
||||
/// emitted in the assistant message. Without it, the model sees shuffled
|
||||
/// results and loses track of which result belongs to which call.
|
||||
///
|
||||
/// Each call still pushes its `TurnEvent::ToolResult` (so the TUI shows each
|
||||
/// tool as it completes) but the returned `Vec` is ordered by the input index.
|
||||
async fn execute_tool_calls_in_parallel<T: ToolExecutor>(
|
||||
tool_executor: &T,
|
||||
turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>,
|
||||
tool_calls: &[zesdex_domain::core::ToolCall],
|
||||
) -> Vec<String> {
|
||||
let semaphore = Arc::new(tokio::sync::Semaphore::new(MAX_PARALLEL_TOOLS));
|
||||
let executor_ref = tool_executor_ref(tool_executor);
|
||||
|
||||
let futures = tool_calls.iter().map(|tc| {
|
||||
let tc = tc.clone();
|
||||
let events = turn_events.clone();
|
||||
let sem = semaphore.clone();
|
||||
async move {
|
||||
// Acquire a permit to bound concurrency across the batch.
|
||||
let _permit = sem.acquire_owned().await;
|
||||
execute_tool_call(executor_ref, &events, &tc).await
|
||||
}
|
||||
});
|
||||
|
||||
futures_util::future::join_all(futures).await
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helper: emit usage event from optional LLM response metadata.
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -108,19 +256,19 @@ fn emit_usage(turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>, usage: Option<(u64,
|
||||
|
||||
/// Service implementation for executing an agent turn asynchronously.
|
||||
///
|
||||
/// # Explore phase
|
||||
///
|
||||
/// Before the main LLM loop begins, [`AgentTurnServiceImpl`] runs a mandatory
|
||||
/// explore phase that spawns ≥3 parallel subagents (code structure, symbol
|
||||
/// index, semantic context) and injects their consolidated findings as a
|
||||
/// system message. See [`ExploreService`] for the trait contract.
|
||||
/// The turn loop is adaptive and token-aware:
|
||||
/// - No mandatory explore phase — the *agent* decides when to call the
|
||||
/// `explore_codebase` tool (see the main prompt), so simple queries skip
|
||||
/// exploration entirely.
|
||||
/// - `max_tokens` / `temperature` adapt to the request length and phase.
|
||||
/// - Repeated tool errors trigger a system recovery note and eventually
|
||||
/// stop the loop instead of burning iterations.
|
||||
/// - Tool outputs are truncated before entering context.
|
||||
/// - Oversized histories are auto-compacted before the next LLM call.
|
||||
pub struct AgentTurnServiceImpl<P: ProviderService, T: ToolExecutor> {
|
||||
provider: Arc<P>,
|
||||
tool_executor: Arc<T>,
|
||||
tool_defs: Vec<ToolDef>,
|
||||
/// Optional explore-phase service. When `Some`, the explore phase runs
|
||||
/// before every turn; when `None` it is skipped (tests, daemon mode).
|
||||
explore_service: Option<Arc<dyn ExploreService>>,
|
||||
}
|
||||
|
||||
impl<P: ProviderService, T: ToolExecutor> AgentTurnServiceImpl<P, T> {
|
||||
@@ -129,19 +277,9 @@ impl<P: ProviderService, T: ToolExecutor> AgentTurnServiceImpl<P, T> {
|
||||
provider,
|
||||
tool_executor,
|
||||
tool_defs,
|
||||
explore_service: None,
|
||||
}
|
||||
}
|
||||
|
||||
/// Attach an optional explore-phase service.
|
||||
///
|
||||
/// When set, every call to `run_turn` will first run the explore phase
|
||||
/// and inject the consolidated context as a system message.
|
||||
pub fn with_explore(mut self, service: Arc<dyn ExploreService>) -> Self {
|
||||
self.explore_service = Some(service);
|
||||
self
|
||||
}
|
||||
|
||||
/// Execute a single LLM call with the current message list, handling
|
||||
/// streaming events and error reporting.
|
||||
async fn call_llm(
|
||||
@@ -149,6 +287,8 @@ impl<P: ProviderService, T: ToolExecutor> AgentTurnServiceImpl<P, T> {
|
||||
messages: &[ChatMessage],
|
||||
abort: &Arc<AtomicBool>,
|
||||
turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>,
|
||||
max_tokens: u32,
|
||||
temperature: f32,
|
||||
) -> Result<(ChatMessage, Option<(u64, u64)>), String> {
|
||||
let on_event = make_stream_callback(abort, turn_events);
|
||||
|
||||
@@ -156,13 +296,39 @@ impl<P: ProviderService, T: ToolExecutor> AgentTurnServiceImpl<P, T> {
|
||||
.chat_stream(
|
||||
messages,
|
||||
Some(self.tool_defs.clone()),
|
||||
Some(4096),
|
||||
Some(0.7),
|
||||
Some(max_tokens),
|
||||
Some(temperature),
|
||||
on_event,
|
||||
)
|
||||
.await
|
||||
.map_err(|e| format!("LLM error: {e}"))
|
||||
}
|
||||
|
||||
/// Auto-compact the history in place if it exceeds the threshold.
|
||||
///
|
||||
/// Runs at most once per turn. Skips the synthetic system prompt that
|
||||
/// this service inserts at index 0.
|
||||
async fn auto_compact_if_needed(&self, messages: &mut Vec<ChatMessage>) {
|
||||
if conversation_chars(messages) <= AUTO_COMPACT_CHARS {
|
||||
return;
|
||||
}
|
||||
// Keep the system prompt (index 0) out of compaction.
|
||||
let sys = messages[0].clone();
|
||||
let mut rest: Vec<ChatMessage> = messages.drain(1..).collect();
|
||||
let before = rest.len();
|
||||
if let Err(e) = super::compact_messages_with_ai(&mut rest, self.provider.as_ref()).await {
|
||||
warn!("auto-compact failed (non-fatal): {e}");
|
||||
}
|
||||
info!(
|
||||
"auto-compacted history: {} messages -> {}",
|
||||
before,
|
||||
rest.len()
|
||||
);
|
||||
let mut rebuilt = Vec::with_capacity(rest.len() + 1);
|
||||
rebuilt.push(sys);
|
||||
rebuilt.extend(rest);
|
||||
*messages = rebuilt;
|
||||
}
|
||||
}
|
||||
|
||||
impl<P: ProviderService, T: ToolExecutor> super::AgentTurnService for AgentTurnServiceImpl<P, T> {
|
||||
@@ -173,73 +339,26 @@ impl<P: ProviderService, T: ToolExecutor> super::AgentTurnService for AgentTurnS
|
||||
params.model
|
||||
);
|
||||
|
||||
// ── Phase 0: Mandatory explore ──────────────────────────────────
|
||||
// Spawn ≥3 parallel subagents to discover code structure, symbols,
|
||||
// and semantic context. The consolidated summary is injected as a
|
||||
// system message before the main agent prompt.
|
||||
if let Some(ref explorer) = self.explore_service {
|
||||
// Determine workspace root from the first message's context or
|
||||
// the first workspace root in params.
|
||||
let user_query = params
|
||||
.messages
|
||||
.last()
|
||||
.map(|m| m.content.clone().unwrap_or_default())
|
||||
.unwrap_or_default();
|
||||
let workspace_root = params
|
||||
.workspace_roots
|
||||
.first()
|
||||
.map(|p| p.to_string_lossy().to_string())
|
||||
.unwrap_or_else(|| ".".to_string());
|
||||
|
||||
push_event(
|
||||
¶ms.turn_events,
|
||||
TurnEvent::SystemNote {
|
||||
kind: "info".into(),
|
||||
message: "🔍 Exploring codebase structure...".into(),
|
||||
},
|
||||
);
|
||||
|
||||
match explorer
|
||||
.explore(&user_query, &workspace_root, ¶ms.turn_events)
|
||||
.await
|
||||
{
|
||||
Ok(output) => {
|
||||
// Insert each context message as a system message.
|
||||
// They go at index 0 and are removed after the turn
|
||||
// like the main agent prompt.
|
||||
for ctx_msg in &output.context_messages {
|
||||
params
|
||||
.messages
|
||||
.insert(0, ChatMessage::system(ctx_msg.clone()));
|
||||
}
|
||||
info!(
|
||||
"Explore phase complete: {} context messages, {}",
|
||||
output.context_messages.len(),
|
||||
output.summary
|
||||
);
|
||||
}
|
||||
Err(e) => {
|
||||
warn!("Explore phase failed (non-fatal): {e}");
|
||||
push_event(
|
||||
¶ms.turn_events,
|
||||
TurnEvent::SystemNote {
|
||||
kind: "warn".into(),
|
||||
message: format!("Explore phase failed: {e}"),
|
||||
},
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Insert system prompt at position 0 once and keep it there for the
|
||||
// entire turn, avoiding per-iteration clones of the full message list.
|
||||
// It is removed before emitting the Compacted event so persistence
|
||||
// does not store the prompt redundantly.
|
||||
params
|
||||
.messages
|
||||
.insert(0, ChatMessage::system(main_agent_prompt()));
|
||||
let original_count = params.messages.len();
|
||||
|
||||
// Estimate request complexity from the last user message.
|
||||
let request_len = params
|
||||
.messages
|
||||
.last()
|
||||
.and_then(|m| m.content.as_deref())
|
||||
.map(str::len)
|
||||
.unwrap_or(0);
|
||||
|
||||
let mut errors = ErrorTracker::default();
|
||||
// Track whether the previous call produced tool calls — used to
|
||||
// lower temperature once the agent starts producing a final answer.
|
||||
let mut saw_tool_calls = false;
|
||||
|
||||
for iteration in 0..MAX_TURN_ITERATIONS {
|
||||
// ── Check abort flag ────────────────────────────────────────
|
||||
if params.abort.load(Ordering::SeqCst) {
|
||||
@@ -254,15 +373,40 @@ impl<P: ProviderService, T: ToolExecutor> super::AgentTurnService for AgentTurnS
|
||||
break;
|
||||
}
|
||||
|
||||
if errors.should_stop() {
|
||||
push_event(
|
||||
¶ms.turn_events,
|
||||
TurnEvent::SystemNote {
|
||||
kind: "warn".into(),
|
||||
message: "Stopping: repeated tool errors without progress".into(),
|
||||
},
|
||||
);
|
||||
break;
|
||||
}
|
||||
|
||||
debug!("agent turn iteration {iteration}");
|
||||
|
||||
// ── Auto-compact oversized history before the LLM call ─────
|
||||
self.auto_compact_if_needed(&mut params.messages).await;
|
||||
|
||||
// ── Adaptive generation parameters ─────────────────────────
|
||||
let max_tokens = adaptive_max_tokens(request_len);
|
||||
// Lower temperature while the agent is still choosing tools to
|
||||
// keep tool selection deterministic; raise it for the final
|
||||
// free-form answer.
|
||||
let temperature = if saw_tool_calls { 0.2 } else { 0.7 };
|
||||
|
||||
// ── Stream start + call LLM ─────────────────────────────────
|
||||
push_event(¶ms.turn_events, TurnEvent::StreamStart);
|
||||
|
||||
// Uses params.messages directly (sys_msg[0] already in place
|
||||
// from the insert above) — no per-iteration clone needed.
|
||||
let result = self
|
||||
.call_llm(¶ms.messages, ¶ms.abort, ¶ms.turn_events)
|
||||
.call_llm(
|
||||
¶ms.messages,
|
||||
¶ms.abort,
|
||||
¶ms.turn_events,
|
||||
max_tokens,
|
||||
temperature,
|
||||
)
|
||||
.await;
|
||||
|
||||
match result {
|
||||
@@ -283,13 +427,49 @@ impl<P: ProviderService, T: ToolExecutor> super::AgentTurnService for AgentTurnS
|
||||
break;
|
||||
}
|
||||
|
||||
saw_tool_calls = true;
|
||||
params.messages.push(assistant_msg);
|
||||
|
||||
// ── Execute each tool call ──────────────────────────
|
||||
//
|
||||
// If the whole batch is made of *read-only* tools
|
||||
// (read/grep/glob/…), run it concurrently with bounded
|
||||
// parallelism — a big latency win for coding turns that
|
||||
// emit several independent lookups in one message. Any
|
||||
// single mutating tool forces the whole batch back to the
|
||||
// safe sequential path so writes never race.
|
||||
//
|
||||
// Results are always collected in the original call order
|
||||
// to honour the tool-calling contract.
|
||||
let parallel = tool_calls.len() > 1
|
||||
&& tool_calls
|
||||
.iter()
|
||||
.all(|tc| self.tool_executor.is_parallel_safe(&tc.function.name));
|
||||
let outputs: Vec<String> = if parallel {
|
||||
execute_tool_calls_in_parallel(
|
||||
self.tool_executor.as_ref(),
|
||||
¶ms.turn_events,
|
||||
&tool_calls,
|
||||
)
|
||||
.await
|
||||
} else {
|
||||
let mut sequential = Vec::with_capacity(tool_calls.len());
|
||||
for tc in &tool_calls {
|
||||
let output =
|
||||
execute_tool_call(self.tool_executor.as_ref(), ¶ms.turn_events, tc)
|
||||
let out = execute_tool_call(
|
||||
self.tool_executor.as_ref(),
|
||||
¶ms.turn_events,
|
||||
tc,
|
||||
)
|
||||
.await;
|
||||
sequential.push(out);
|
||||
}
|
||||
sequential
|
||||
};
|
||||
|
||||
for (tc, output) in tool_calls.iter().zip(outputs) {
|
||||
if output.starts_with("Error:") {
|
||||
errors.record(&tc.function.name, &output, &mut params.messages);
|
||||
}
|
||||
params
|
||||
.messages
|
||||
.push(ChatMessage::tool(tc.id.clone(), output));
|
||||
@@ -370,3 +550,147 @@ pub async fn compact_messages_with_ai<P: ProviderService>(
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Tests
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
#[test]
|
||||
fn truncate_short_output_is_unchanged() {
|
||||
let out = "short".to_string();
|
||||
assert_eq!(truncate_tool_output(out.clone()), out);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn truncate_long_output_preserves_head_and_marks_cut() {
|
||||
let long = "x".repeat(TOOL_OUTPUT_MAX_CHARS + 500);
|
||||
let truncated = truncate_tool_output(long.clone());
|
||||
assert!(truncated.len() < long.len());
|
||||
assert!(truncated.contains("...[truncated"));
|
||||
assert!(truncated.starts_with("xxx"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn adaptive_max_tokens_scales_with_request_len() {
|
||||
assert_eq!(adaptive_max_tokens(10), 800);
|
||||
assert_eq!(adaptive_max_tokens(200), 1600);
|
||||
assert_eq!(adaptive_max_tokens(5000), 4096);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn error_tracker_injects_recovery_note_after_repeats() {
|
||||
let mut tracker = ErrorTracker::default();
|
||||
let mut messages: Vec<ChatMessage> = Vec::new();
|
||||
tracker.record("read", "Error: File not found", &mut messages);
|
||||
tracker.record("read", "Error: File not found", &mut messages);
|
||||
assert!(!tracker.should_stop());
|
||||
// Third consecutive failure → recovery note injected.
|
||||
tracker.record("read", "Error: File not found", &mut messages);
|
||||
assert!(messages.iter().any(|m| m
|
||||
.content
|
||||
.as_deref()
|
||||
.is_some_and(|c| c.contains("[System note]"))));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn error_tracker_stops_after_too_many_errors() {
|
||||
let mut tracker = ErrorTracker::default();
|
||||
let mut messages: Vec<ChatMessage> = Vec::new();
|
||||
for i in 0..MAX_TOTAL_TOOL_ERRORS {
|
||||
tracker.record("bash", &format!("Error: boom {i}"), &mut messages);
|
||||
}
|
||||
assert!(tracker.should_stop());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn conversation_chars_sums_content_only() {
|
||||
let messages = vec![
|
||||
ChatMessage::system("sys".to_string()),
|
||||
ChatMessage::user("hello world".to_string()),
|
||||
ChatMessage::tool("id".to_string(), "output".to_string()),
|
||||
];
|
||||
assert_eq!(conversation_chars(&messages), 3 + 11 + 6);
|
||||
}
|
||||
|
||||
/// A fake executor that reports parallel-safety for read-only tools and
|
||||
/// whose `execute` sleeps on the first call to prove the batch runs
|
||||
/// concurrently (a sequential loop would pay the sleep per call).
|
||||
struct FakeExecutor;
|
||||
|
||||
impl ToolExecutor for FakeExecutor {
|
||||
async fn execute(&self, name: &str, _args: &serde_json::Value) -> anyhow::Result<String> {
|
||||
if name == "read" {
|
||||
// 30ms sleep on every read; a parallel batch of 3 would
|
||||
// finish in ~30ms instead of ~90ms sequentially.
|
||||
tokio::time::sleep(std::time::Duration::from_millis(30)).await;
|
||||
}
|
||||
Ok(format!("out:{name}"))
|
||||
}
|
||||
|
||||
fn is_parallel_safe(&self, name: &str) -> bool {
|
||||
matches!(name, "read" | "grep")
|
||||
}
|
||||
}
|
||||
|
||||
fn tc(name: &str, id: usize) -> zesdex_domain::core::ToolCall {
|
||||
zesdex_domain::core::ToolCall {
|
||||
id: format!("call_{id}"),
|
||||
type_: "function".to_string(),
|
||||
function: zesdex_domain::core::ToolFunction {
|
||||
name: name.to_string(),
|
||||
arguments: serde_json::Value::String(String::new()),
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parallel_batch_runs_concurrently_and_preserves_order() {
|
||||
let executor = FakeExecutor;
|
||||
let events = Arc::new(Mutex::new(VecDeque::new()));
|
||||
let calls = vec![tc("read", 1), tc("grep", 2), tc("read", 3)];
|
||||
|
||||
// All three are parallel-safe.
|
||||
assert!(calls
|
||||
.iter()
|
||||
.all(|c| executor.is_parallel_safe(&c.function.name)));
|
||||
|
||||
let rt = tokio::runtime::Builder::new_multi_thread()
|
||||
.enable_time()
|
||||
.build()
|
||||
.unwrap();
|
||||
let started = std::time::Instant::now();
|
||||
let outputs = rt.block_on(execute_tool_calls_in_parallel(&executor, &events, &calls));
|
||||
let elapsed = started.elapsed();
|
||||
|
||||
// Results are in *original* call order (read, grep, read).
|
||||
assert_eq!(
|
||||
outputs,
|
||||
vec![
|
||||
"out:read".to_string(),
|
||||
"out:grep".to_string(),
|
||||
"out:read".to_string()
|
||||
]
|
||||
);
|
||||
// Two reads sleep 30ms each; sequential would take ~60ms+ for the
|
||||
// two reads, parallel keeps the whole batch under 60ms.
|
||||
assert!(
|
||||
elapsed < std::time::Duration::from_millis(60),
|
||||
"batch took {elapsed:?}, expected parallel execution"
|
||||
);
|
||||
assert!(elapsed >= std::time::Duration::from_millis(25));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn mutating_batch_falls_back_to_sequential_path() {
|
||||
// A batch containing a mutating tool is not eligible for the parallel
|
||||
// path, so the main loop keeps results ordered and side-effects safe.
|
||||
let executor = FakeExecutor;
|
||||
let calls = [tc("read", 1), tc("edit", 2)];
|
||||
assert!(!calls
|
||||
.iter()
|
||||
.all(|c| executor.is_parallel_safe(&c.function.name)));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -52,5 +52,5 @@ pub use cms::{
|
||||
|
||||
pub use agent::{
|
||||
turn_service::{compact_messages_with_ai, AgentTurnServiceImpl},
|
||||
AgentTurnService, ExploreOutput, ExploreService, ToolExecutor,
|
||||
AgentTurnService, ToolExecutor,
|
||||
};
|
||||
|
||||
@@ -22,12 +22,20 @@ pub fn main_agent_prompt() -> String {
|
||||
You are Zesdex, an AI coding assistant. You have access to various tools \
|
||||
via native function calling to help the user.
|
||||
|
||||
TOKEN BUDGET — BE EFFICIENT:
|
||||
- For simple/factual questions, answer directly. Do NOT call tools.
|
||||
- For complex or unfamiliar code tasks, call `explore_codebase` ONCE at the \
|
||||
start to locate relevant code, then work from that context.
|
||||
- Keep tool usage minimal: prefer `grep`/`glob`/`read` for targeted lookups; \
|
||||
avoid re-reading files you already have in context.
|
||||
- Keep responses concise; do not repeat tool output verbatim.
|
||||
|
||||
CRITICAL DIRECTIVES & PRIORITY HIERARCHY:
|
||||
1. WORKFLOW FIRST: For any multi-step, complex, or non-trivial task, \
|
||||
you MUST prioritise using `workflow_run` (to construct and execute a \
|
||||
multi-phase YAML workflow) or `hive_mind` (to orchestrate parallel \
|
||||
autonomous agents). Workflows are your primary strategy.
|
||||
2. PLANNING & TODOS: Use `plan_enter` to establish high-level \
|
||||
2. PLANNING & TODOs: Use `plan_enter` to establish high-level \
|
||||
architectural plans and `todowrite` to maintain granular task checklists.
|
||||
3. REASONING: Use `seq_think` for deep step-by-step analysis.
|
||||
4. TOOL EXECUTION: Execute individual tools (file edits, terminal commands) \
|
||||
@@ -70,6 +78,35 @@ executed, and modified files. Format as a clear bulleted list."
|
||||
.to_string()
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Adaptive explore: directives
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Directive for a single lightweight context-scout subagent.
|
||||
pub fn explore_scout_directive() -> String {
|
||||
"\
|
||||
You are a codebase context scout. \
|
||||
Given the workspace root, quickly locate the code that is most relevant \
|
||||
to the user's request: \
|
||||
1. Run semantic_search once with the user's key terms. \
|
||||
2. Read up to the 3 most relevant files (use grep for symbols if needed). \
|
||||
3. Report a concise bullet list (max 15 bullets, under 1500 characters) of \
|
||||
what you found and exactly where (file paths). \
|
||||
Do NOT rebuild the index. Do NOT enumerate unrelated files. Be brief."
|
||||
.to_string()
|
||||
}
|
||||
|
||||
/// Build a system note injected after repeated tool errors to steer the
|
||||
/// agent toward an alternative approach instead of retrying the same call.
|
||||
pub fn error_recovery_note(tool_name: &str, last_error: &str) -> String {
|
||||
format!(
|
||||
"\
|
||||
[System note] The tool `{tool_name}` failed repeatedly with: \"{last_error}\". \
|
||||
Try an alternative approach (verify paths, correct arguments, use a \
|
||||
different tool, or finish without this tool). Do NOT retry the same call."
|
||||
)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
@@ -89,4 +126,18 @@ mod tests {
|
||||
assert!(prompt.contains("/home"));
|
||||
assert!(prompt.contains("/home/project"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn explore_scout_directive_is_concise_and_mentions_tools() {
|
||||
let scout = explore_scout_directive();
|
||||
assert!(scout.contains("scout"));
|
||||
assert!(scout.contains("semantic_search"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn error_recovery_note_suggests_alternative() {
|
||||
let note = error_recovery_note("read", "File not found");
|
||||
assert!(note.contains("read"));
|
||||
assert!(note.contains("alternative"));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -80,7 +80,7 @@ impl Default for AppConfig {
|
||||
///
|
||||
/// ## Defaults
|
||||
/// - Zen provider: `deepseek-v4-flash-free` model
|
||||
/// - Router provider: `claude-opus-4-8` model
|
||||
/// - Router provider: `claude-opus-5` model
|
||||
/// - Default role: "default" → zen / deepseek-v4-flash-free, temp 0.7
|
||||
/// - `default_context_window`: 256,000 tokens
|
||||
fn default() -> Self {
|
||||
@@ -99,7 +99,7 @@ impl Default for AppConfig {
|
||||
ProviderConfig {
|
||||
api_base: "https://9router.asepharyana.my.id/v1".to_string(),
|
||||
api_key_env: Some("ROUTER_API_KEY".to_string()),
|
||||
default_model: Some("claude-opus-4-8".to_string()),
|
||||
default_model: Some("claude-opus-5".to_string()),
|
||||
default_api_key: None,
|
||||
},
|
||||
);
|
||||
|
||||
@@ -47,6 +47,7 @@ pub use repository::SettingsRepository;
|
||||
pub use service::ConversationService;
|
||||
pub use service::MemoryService;
|
||||
pub use service::SettingsService;
|
||||
pub use settings::resolve_effective_model;
|
||||
pub use settings::InternetMode;
|
||||
pub use settings::Settings;
|
||||
pub use settings::SettingsFlags;
|
||||
|
||||
@@ -23,6 +23,8 @@ use std::collections::HashMap;
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
use super::app_config::AppConfig;
|
||||
|
||||
/// Controls how much network access the agent is permitted during a session.
|
||||
///
|
||||
/// ## Variants
|
||||
@@ -112,3 +114,86 @@ impl Default for Settings {
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Pick the effective model name for the main agent.
|
||||
///
|
||||
/// When `settings.provider` is `"claude"` (auto-detected from
|
||||
/// `~/.claude/settings.json`), the provider's `default_model` (or the
|
||||
/// app-level `default_model`) wins over a possibly-stale persisted
|
||||
/// `settings.model`. Otherwise the user's explicit `settings.model` is used.
|
||||
///
|
||||
/// Why: the user's custom Claude endpoint (URL + API key from
|
||||
/// `~/.claude/settings.json`) implies Opus as the model; a stale
|
||||
/// `settings.json` (e.g. "deepseek-v4-flash-free") must not override it.
|
||||
pub fn resolve_effective_model(settings: &Settings, app_config: &AppConfig) -> String {
|
||||
if settings.provider == "claude" {
|
||||
if let Some(m) = app_config
|
||||
.providers
|
||||
.get("claude")
|
||||
.and_then(|p| p.default_model.clone())
|
||||
{
|
||||
return m;
|
||||
}
|
||||
return app_config.default_model.clone();
|
||||
}
|
||||
settings.model.clone()
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::cms::app_config::AppConfig;
|
||||
|
||||
fn claude_app_config() -> AppConfig {
|
||||
let mut cfg = AppConfig::default();
|
||||
cfg.providers.insert(
|
||||
"claude".to_string(),
|
||||
crate::cms::ProviderConfig {
|
||||
api_base: "https://9router.example/v1".to_string(),
|
||||
api_key_env: Some("ANTHROPIC_API_KEY".to_string()),
|
||||
default_model: Some("claude-opus-5".to_string()),
|
||||
default_api_key: Some("sk-test".to_string()),
|
||||
},
|
||||
);
|
||||
cfg.default_provider = "claude".to_string();
|
||||
cfg.default_model = "claude-opus-5".to_string();
|
||||
cfg
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn claude_provider_uses_opus_model_over_stale_settings_model() {
|
||||
let settings = Settings {
|
||||
provider: "claude".to_string(),
|
||||
model: "deepseek-v4-flash-free".to_string(), // stale persisted
|
||||
..Settings::default()
|
||||
};
|
||||
|
||||
let model = resolve_effective_model(&settings, &claude_app_config());
|
||||
assert_eq!(model, "claude-opus-5");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn non_claude_provider_uses_settings_model() {
|
||||
let settings = Settings {
|
||||
provider: "zen".to_string(),
|
||||
model: "my-model".to_string(),
|
||||
..Settings::default()
|
||||
};
|
||||
|
||||
let model = resolve_effective_model(&settings, &AppConfig::default());
|
||||
assert_eq!(model, "my-model");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn claude_falls_back_to_app_default() {
|
||||
let settings = Settings {
|
||||
provider: "claude".to_string(),
|
||||
model: String::new(),
|
||||
..Settings::default()
|
||||
};
|
||||
|
||||
let cfg = AppConfig::default();
|
||||
let model = resolve_effective_model(&settings, &cfg);
|
||||
assert_eq!(model, cfg.default_model);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,304 +1,141 @@
|
||||
//! Mandatory explore phase — spawns ≥3 parallel subagents to discover
|
||||
//! codebase context before every agent turn, visible in the TUI workflow tab.
|
||||
//! `explore_codebase` tool — lazy, agent-initiated codebase exploration.
|
||||
//!
|
||||
//! The main agent decides (via the system prompt) when it needs codebase
|
||||
//! context. Unlike the old mandatory explore phase (which ran 3 subagents on
|
||||
//! every turn regardless of the question), this tool is invoked only when the
|
||||
//! agent judges it necessary — saving tokens on trivial queries while keeping
|
||||
//! context available for complex tasks.
|
||||
//!
|
||||
//! # Flow
|
||||
//!
|
||||
//! `ExploreServiceImpl::explore()` →
|
||||
//!
|
||||
//! 1. Push `WorkflowAgentUpdate { Pending }` for each agent onto the turn-event
|
||||
//! queue so the TUI workflow tab shows all 3.
|
||||
//! 2. Spawn **Code Structure** subagent (thread + tokio runtime).
|
||||
//! 3. Spawn **Symbol Index** subagent (thread + tokio runtime).
|
||||
//! 4. Spawn **Semantic Context** subagent (thread + tokio runtime).
|
||||
//! 5. Join all handles via `spawn_blocking`.
|
||||
//! 6. Push `Completed` / `Failed` events for each agent.
|
||||
//! 7. Consolidate findings into a system message → return.
|
||||
//! `ExploreCodebase::run` →
|
||||
//! 1. Parse the user's goal / target from args.
|
||||
//! 2. Resolve subagent provider credentials from settings.
|
||||
//! 3. Spawn a single "context scout" subagent (read-only, semantic_search +
|
||||
//! read of up to 3 relevant files).
|
||||
//! 4. Join the result and return a concise bullet summary as a tool message.
|
||||
|
||||
use anyhow::Result;
|
||||
use serde_json::{json, Value};
|
||||
use tracing::{info, warn};
|
||||
|
||||
use zesdex_domain::agent::prompt::explore_scout_directive;
|
||||
use zesdex_domain::cms::{AppConfigRepository, SettingsRepository};
|
||||
use zesdex_domain::core::Store;
|
||||
|
||||
use crate::persistence::{JsonAppConfigRepository, JsonSettingsRepository};
|
||||
use crate::subagent::context::SubagentContext;
|
||||
use crate::subagent::division::AccessTier;
|
||||
use crate::subagent::engine::run_agent;
|
||||
use crate::tools::ToolCtx;
|
||||
use anyhow::{Context, Result};
|
||||
use std::collections::VecDeque;
|
||||
use std::future::Future;
|
||||
use std::pin::Pin;
|
||||
use std::sync::{Arc, Mutex};
|
||||
use std::thread;
|
||||
use tracing::{info, warn};
|
||||
use zesdex_application::agent::{ExploreOutput, ExploreService};
|
||||
use zesdex_domain::agent::{AgentStatus, TurnEvent};
|
||||
use crate::tools::{Tool, ToolCtx};
|
||||
|
||||
/// Number of parallel explore subagents.
|
||||
const EXPLORE_AGENT_COUNT: usize = 3;
|
||||
/// Maximum characters of the scout's final output to keep in context.
|
||||
/// The scout is directed to stay under 1500 chars, but this ceiling protects
|
||||
/// against rogue output.
|
||||
const EXPLORE_OUTPUT_MAX_CHARS: usize = 4000;
|
||||
|
||||
/// IDs for each explore agent (shown in the workflow tab).
|
||||
const EXPLORE_IDS: [&str; 3] = ["explore-structure", "explore-symbols", "explore-context"];
|
||||
/// `explore_codebase` tool — ask a read-only context-scout subagent to
|
||||
/// locate relevant code for the current task.
|
||||
pub struct ExploreCodebase;
|
||||
|
||||
/// Display names for the TUI workflow tab.
|
||||
const EXPLORE_LABELS: [&str; 3] = [
|
||||
"📁 Code Structure",
|
||||
"🔣 Symbol Index",
|
||||
"🔍 Semantic Context",
|
||||
];
|
||||
|
||||
/// Directives for each explore subagent.
|
||||
const EXPLORE_DIRECTIVES: [&str; 3] = [
|
||||
// Agent 0: Code Structure
|
||||
"You are a codebase structure explorer.\n\
|
||||
1. List all top-level directories and files in the workspace root.\n\
|
||||
2. Read Cargo.toml, package.json, or pyproject.toml at the root.\n\
|
||||
3. List the apps/ or src/ directory contents.\n\
|
||||
4. Identify main entry points (main.rs, main.py, index.ts, etc.).\n\
|
||||
5. Count files by extension type.\n\
|
||||
Use the ls_dir, read, grep, and glob tools. Be concise.",
|
||||
// Agent 1: Symbol Index
|
||||
"You are a symbol index explorer.\n\
|
||||
1. Call the 'rebuild_index' tool to rebuild the symbol index.\n\
|
||||
2. Call the 'list_symbols' tool with max_results: 100.\n\
|
||||
3. Identify public APIs, entry points, and key types.\n\
|
||||
4. Group symbols by language and kind.\n\
|
||||
Be concise. Report what symbols exist and where they live.",
|
||||
// Agent 2: Semantic Context
|
||||
"You are a semantic context explorer.\n\
|
||||
1. Call the 'rebuild_index' tool to ensure the index is fresh.\n\
|
||||
2. Search for symbols related to the user's query using semantic_search.\n\
|
||||
3. Search for config files, env variables, and settings.\n\
|
||||
4. Search for test files and test patterns.\n\
|
||||
Be concise. Report relevant code areas for the task.\n\
|
||||
Use the semantic_search, grep, glob, and read tools.",
|
||||
];
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Credentials
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// LLM credentials for explore subagents.
|
||||
pub struct Credentials {
|
||||
pub base_url: String,
|
||||
pub api_key: String,
|
||||
pub model: String,
|
||||
impl Tool for ExploreCodebase {
|
||||
fn name(&self) -> &'static str {
|
||||
"explore_codebase"
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// ExploreServiceImpl — implements the application-layer trait
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Concrete [`ExploreService`] that the turn service calls.
|
||||
///
|
||||
/// Owns a shared `ToolCtx` and LLM credentials. Each call to `explore()`
|
||||
/// spawns 3 subagents in parallel with TUI workflow-tab visibility.
|
||||
pub struct ExploreServiceImpl {
|
||||
tool_ctx: ToolCtx,
|
||||
credentials: Credentials,
|
||||
fn description(&self) -> &'static str {
|
||||
"Explore the codebase to locate code relevant to a task. Use this \
|
||||
once at the start of complex or unfamiliar tasks (implementing a \
|
||||
feature, fixing a bug, refactoring, navigating a large repo). \
|
||||
Do NOT use for simple factual questions about the current \
|
||||
conversation."
|
||||
}
|
||||
|
||||
impl ExploreServiceImpl {
|
||||
pub fn new(tool_ctx: ToolCtx, credentials: Credentials) -> Self {
|
||||
ExploreServiceImpl {
|
||||
tool_ctx,
|
||||
credentials,
|
||||
fn parameters(&self) -> Value {
|
||||
json!({
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"goal": {
|
||||
"type": "string",
|
||||
"description": "The task or question to explore for"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl ExploreService for ExploreServiceImpl {
|
||||
fn explore<'a>(
|
||||
&'a self,
|
||||
query: &'a str,
|
||||
workspace_root: &'a str,
|
||||
turn_events: &'a Arc<Mutex<VecDeque<TurnEvent>>>,
|
||||
) -> Pin<Box<dyn Future<Output = Result<ExploreOutput>> + Send + 'a>> {
|
||||
Box::pin(async move {
|
||||
let context = run_explore_phase(
|
||||
query,
|
||||
workspace_root,
|
||||
&self.tool_ctx,
|
||||
&self.credentials,
|
||||
turn_events,
|
||||
)
|
||||
.await?;
|
||||
|
||||
Ok(ExploreOutput {
|
||||
context_messages: vec![context],
|
||||
summary: format!("{EXPLORE_AGENT_COUNT} explore agents dispatched"),
|
||||
})
|
||||
},
|
||||
"required": ["goal"]
|
||||
})
|
||||
}
|
||||
|
||||
fn run(&self, ctx: &ToolCtx, args: &Value) -> Result<String> {
|
||||
let goal = args
|
||||
.get("goal")
|
||||
.and_then(|v| v.as_str())
|
||||
.unwrap_or("")
|
||||
.trim()
|
||||
.to_string();
|
||||
|
||||
if goal.is_empty() {
|
||||
return Err(anyhow::anyhow!("missing non-empty 'goal'"));
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Helpers for pushing workflow events
|
||||
// ---------------------------------------------------------------------------
|
||||
info!("explore_codebase: {goal}");
|
||||
|
||||
fn push_event(events: &Arc<Mutex<VecDeque<TurnEvent>>>, event: TurnEvent) {
|
||||
if let Ok(mut q) = events.lock() {
|
||||
q.push_back(event);
|
||||
}
|
||||
}
|
||||
let store = Store::new();
|
||||
let settings = JsonSettingsRepository::new()
|
||||
.load(&store.base_dir)
|
||||
.unwrap_or_default();
|
||||
let app_config = JsonAppConfigRepository::new()
|
||||
.load(&store.base_dir)
|
||||
.unwrap_or_default();
|
||||
|
||||
fn emit_pending(events: &Arc<Mutex<VecDeque<TurnEvent>>>, agent_id: &str, display: &str) {
|
||||
push_event(
|
||||
events,
|
||||
TurnEvent::WorkflowAgentUpdate {
|
||||
agent_id: agent_id.to_string(),
|
||||
agent_name: display.to_string(),
|
||||
status: AgentStatus::Pending,
|
||||
},
|
||||
let (provider, model) =
|
||||
crate::subagent::provider::resolve_subagent_provider(&settings, &app_config);
|
||||
|
||||
let base_url = app_config
|
||||
.providers
|
||||
.get(&provider)
|
||||
.map(|p| p.api_base.clone())
|
||||
.unwrap_or_else(|| zesdex_domain::agent::defaults::DEFAULT_API_BASE.to_string());
|
||||
|
||||
let api_key = crate::llm::provider::resolve_api_key(&settings, &app_config);
|
||||
|
||||
let workspace_root = ctx
|
||||
.workspaces
|
||||
.first()
|
||||
.map(|p| p.to_string_lossy().to_string())
|
||||
.unwrap_or_else(|| ".".to_string());
|
||||
|
||||
// One lightweight scout — no parallel agents, no index rebuild.
|
||||
let directive = format!(
|
||||
"{}\n\nUser's task: {goal}\nWorkspace root: {workspace_root}",
|
||||
explore_scout_directive()
|
||||
);
|
||||
}
|
||||
|
||||
fn emit_running(events: &Arc<Mutex<VecDeque<TurnEvent>>>, agent_id: &str, display: &str) {
|
||||
push_event(
|
||||
events,
|
||||
TurnEvent::WorkflowAgentUpdate {
|
||||
agent_id: agent_id.to_string(),
|
||||
agent_name: display.to_string(),
|
||||
status: AgentStatus::Running,
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
fn emit_completed(events: &Arc<Mutex<VecDeque<TurnEvent>>>, agent_id: &str, display: &str) {
|
||||
push_event(
|
||||
events,
|
||||
TurnEvent::WorkflowAgentUpdate {
|
||||
agent_id: agent_id.to_string(),
|
||||
agent_name: display.to_string(),
|
||||
status: AgentStatus::Completed,
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
fn emit_failed(events: &Arc<Mutex<VecDeque<TurnEvent>>>, agent_id: &str, display: &str, msg: &str) {
|
||||
push_event(
|
||||
events,
|
||||
TurnEvent::WorkflowAgentUpdate {
|
||||
agent_id: agent_id.to_string(),
|
||||
agent_name: display.to_string(),
|
||||
status: AgentStatus::Failed(msg.to_string()),
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Core orchestration
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Spawn `EXPLORE_AGENT_COUNT` subagents in parallel, emit workflow events
|
||||
/// for the TUI tab, join, and consolidate.
|
||||
async fn run_explore_phase(
|
||||
query: &str,
|
||||
workspace_root: &str,
|
||||
tool_ctx: &ToolCtx,
|
||||
credentials: &Credentials,
|
||||
turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>,
|
||||
) -> Result<String> {
|
||||
// ── 1. Emit Pending for all agents (appears instantly in workflow tab) ─
|
||||
for (i, &id) in EXPLORE_IDS.iter().enumerate() {
|
||||
emit_pending(turn_events, id, EXPLORE_LABELS[i]);
|
||||
}
|
||||
|
||||
// ── 2. Prepare directives ───────────────────────────────────────────
|
||||
let mut directives: Vec<String> = Vec::with_capacity(EXPLORE_AGENT_COUNT);
|
||||
for (i, &d) in EXPLORE_DIRECTIVES.iter().enumerate() {
|
||||
let mut d = d.to_string();
|
||||
if i == 2 {
|
||||
d.push_str(&format!("\n\nThe user's current query is: \"{query}\""));
|
||||
}
|
||||
d.push_str(&format!("\n\nWorkspace root: {workspace_root}"));
|
||||
directives.push(d);
|
||||
}
|
||||
|
||||
// ── 3. Spawn all agents on threads ──────────────────────────────────
|
||||
let mut handles: Vec<(usize, thread::JoinHandle<Result<String>>)> =
|
||||
Vec::with_capacity(EXPLORE_AGENT_COUNT);
|
||||
|
||||
for i in 0..EXPLORE_AGENT_COUNT {
|
||||
emit_running(turn_events, EXPLORE_IDS[i], EXPLORE_LABELS[i]);
|
||||
|
||||
let ctx = SubagentContext::new(
|
||||
directives[i].clone(),
|
||||
tool_ctx.clone(),
|
||||
let subagent_ctx = SubagentContext::new(
|
||||
directive.clone(),
|
||||
ctx.clone(),
|
||||
"read".to_string(),
|
||||
credentials.base_url.clone(),
|
||||
credentials.api_key.clone(),
|
||||
credentials.model.clone(),
|
||||
base_url,
|
||||
api_key,
|
||||
model,
|
||||
);
|
||||
|
||||
let directive = directives[i].clone();
|
||||
let tc = tool_ctx.clone();
|
||||
let rt = crate::runtime::runtime();
|
||||
let result = rt.block_on(run_agent(
|
||||
subagent_ctx,
|
||||
&directive,
|
||||
AccessTier::Read,
|
||||
ctx.clone(),
|
||||
))?;
|
||||
|
||||
let handle = thread::spawn(move || {
|
||||
let rt =
|
||||
tokio::runtime::Runtime::new().context("create explore subagent tokio runtime")?;
|
||||
rt.block_on(run_agent(ctx, &directive, AccessTier::Read, tc))
|
||||
});
|
||||
|
||||
handles.push((i, handle));
|
||||
}
|
||||
|
||||
// ── 4. Join handles via spawn_blocking ──────────────────────────────
|
||||
let turn_events_clone = Arc::clone(turn_events);
|
||||
let results: Vec<(usize, String, bool)> = tokio::task::spawn_blocking(move || {
|
||||
let mut out = Vec::with_capacity(EXPLORE_AGENT_COUNT);
|
||||
for (i, handle) in handles {
|
||||
let entry = match handle.join() {
|
||||
Ok(Ok(output)) => {
|
||||
info!(agent = i, "explore subagent completed");
|
||||
emit_completed(&turn_events_clone, EXPLORE_IDS[i], EXPLORE_LABELS[i]);
|
||||
(i, output, true)
|
||||
}
|
||||
Ok(Err(e)) => {
|
||||
warn!(agent = i, error = %e, "explore subagent failed");
|
||||
emit_failed(
|
||||
&turn_events_clone,
|
||||
EXPLORE_IDS[i],
|
||||
EXPLORE_LABELS[i],
|
||||
&e.to_string(),
|
||||
let mut out = format!("[Codebase scout report]\n{goal}\n\n----------\n{}", result);
|
||||
if out.len() > EXPLORE_OUTPUT_MAX_CHARS {
|
||||
warn!(
|
||||
"explore_codebase output truncated: {} chars -> {}",
|
||||
out.len(),
|
||||
EXPLORE_OUTPUT_MAX_CHARS
|
||||
);
|
||||
(i, format!("Error: {e}"), false)
|
||||
out.truncate(EXPLORE_OUTPUT_MAX_CHARS);
|
||||
out.push_str("\n...[truncated]");
|
||||
}
|
||||
Err(e) => {
|
||||
warn!(agent = i, error = ?e, "explore subagent panicked");
|
||||
emit_failed(
|
||||
&turn_events_clone,
|
||||
EXPLORE_IDS[i],
|
||||
EXPLORE_LABELS[i],
|
||||
"thread panicked",
|
||||
);
|
||||
(i, format!("Thread panic: {e:?}"), false)
|
||||
}
|
||||
};
|
||||
out.push(entry);
|
||||
}
|
||||
out
|
||||
})
|
||||
.await
|
||||
.context("explore join task panicked")?;
|
||||
|
||||
// ── 5. Build consolidated context ───────────────────────────────────
|
||||
Ok(build_explore_context(&results))
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Consolidation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Format explore results as a system-level context message.
|
||||
fn build_explore_context(results: &[(usize, String, bool)]) -> String {
|
||||
let success_count = results.iter().filter(|r| r.2).count();
|
||||
let total = results.len();
|
||||
|
||||
let mut msg = format!("[Explore Phase — {success_count}/{total} agents succeeded]\n\n");
|
||||
|
||||
for (i, output, success) in results {
|
||||
let label = EXPLORE_LABELS.get(*i).unwrap_or(&"❓ Unknown");
|
||||
if *success {
|
||||
msg.push_str(&format!("=== {label} ===\n{output}\n\n"));
|
||||
} else {
|
||||
msg.push_str(&format!("=== {label} (FAILED) ===\n{output}\n\n"));
|
||||
Ok(out)
|
||||
}
|
||||
}
|
||||
|
||||
msg
|
||||
}
|
||||
|
||||
@@ -34,6 +34,7 @@ pub mod llm;
|
||||
pub mod mcp;
|
||||
pub mod middleware;
|
||||
pub mod persistence;
|
||||
pub mod runtime;
|
||||
pub mod subagent;
|
||||
pub mod tools;
|
||||
pub mod utils;
|
||||
|
||||
@@ -72,27 +72,24 @@ fn detect_claude_settings_provider() -> Option<(ProviderConfig, Option<String>)>
|
||||
))
|
||||
}
|
||||
|
||||
impl AppConfigRepository for JsonAppConfigRepository {
|
||||
fn load(&self, base_dir: &Path) -> Result<AppConfig, RepositoryError> {
|
||||
let path = base_dir.join("app_config.json");
|
||||
let mut cfg: AppConfig = match std::fs::read_to_string(&path) {
|
||||
Ok(s) => serde_json::from_str(&s)?,
|
||||
Err(e) if e.kind() == std::io::ErrorKind::NotFound => AppConfig::default(),
|
||||
Err(e) => return Err(RepositoryError::Io(e)),
|
||||
};
|
||||
|
||||
let defaults = AppConfig::default();
|
||||
for (name, provider) in defaults.providers {
|
||||
cfg.providers.entry(name).or_insert(provider);
|
||||
}
|
||||
|
||||
if let Some((claude_provider, custom_model)) = detect_claude_settings_provider() {
|
||||
cfg.providers
|
||||
.entry("claude".to_string())
|
||||
.or_insert(claude_provider);
|
||||
/// Apply a detected Claude provider + custom model onto an `AppConfig`.
|
||||
///
|
||||
/// Pure (no I/O) so it can be unit-tested. Flow:
|
||||
/// 1. Always `insert`s the "claude" provider (refreshing a possibly stale
|
||||
/// persisted entry with the current base URL + key from settings.json).
|
||||
/// 2. Registers known Claude model roles if missing.
|
||||
/// 3. Always sets `default_provider = "claude"` and
|
||||
/// `default_model = custom_model.unwrap_or("claude-opus-5")` so Opus
|
||||
/// is the default whenever `~/.claude/settings.json` is present.
|
||||
fn apply_claude_provider(
|
||||
cfg: &mut AppConfig,
|
||||
claude_provider: ProviderConfig,
|
||||
custom_model: Option<String>,
|
||||
) {
|
||||
cfg.providers.insert("claude".to_string(), claude_provider);
|
||||
|
||||
let claude_models: [(&str, &str); 3] = [
|
||||
("claude-opus-4-8", "claude-opus-4-8"),
|
||||
("claude-opus-5", "claude-opus-5"),
|
||||
("claude-sonnet-5", "claude-sonnet-5"),
|
||||
("claude-haiku-4-5", "claude-haiku-4-5-20251001"),
|
||||
];
|
||||
@@ -118,10 +115,28 @@ impl AppConfigRepository for JsonAppConfigRepository {
|
||||
});
|
||||
}
|
||||
|
||||
if cfg.default_provider == defaults.default_provider {
|
||||
// Always prefer the Claude provider + Opus model when settings.json
|
||||
// is present — this is the user's explicit custom endpoint choice.
|
||||
cfg.default_provider = "claude".to_string();
|
||||
cfg.default_model = custom_model.unwrap_or_else(|| "claude-opus-4-8".to_string());
|
||||
cfg.default_model = custom_model.unwrap_or_else(|| "claude-opus-5".to_string());
|
||||
}
|
||||
|
||||
impl AppConfigRepository for JsonAppConfigRepository {
|
||||
fn load(&self, base_dir: &Path) -> Result<AppConfig, RepositoryError> {
|
||||
let path = base_dir.join("app_config.json");
|
||||
let mut cfg: AppConfig = match std::fs::read_to_string(&path) {
|
||||
Ok(s) => serde_json::from_str(&s)?,
|
||||
Err(e) if e.kind() == std::io::ErrorKind::NotFound => AppConfig::default(),
|
||||
Err(e) => return Err(RepositoryError::Io(e)),
|
||||
};
|
||||
|
||||
let defaults = AppConfig::default();
|
||||
for (name, provider) in defaults.providers {
|
||||
cfg.providers.entry(name).or_insert(provider);
|
||||
}
|
||||
|
||||
if let Some((claude_provider, custom_model)) = detect_claude_settings_provider() {
|
||||
apply_claude_provider(&mut cfg, claude_provider, custom_model);
|
||||
}
|
||||
|
||||
Ok(cfg)
|
||||
@@ -134,3 +149,106 @@ impl AppConfigRepository for JsonAppConfigRepository {
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::collections::HashMap;
|
||||
|
||||
fn claude_provider(base: &str, key: Option<&str>) -> ProviderConfig {
|
||||
ProviderConfig {
|
||||
api_base: base.to_string(),
|
||||
api_key_env: Some("ANTHROPIC_API_KEY".to_string()),
|
||||
default_model: Some("claude-opus-5".to_string()),
|
||||
default_api_key: key.map(|s| s.to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn claude_settings_parse_env() {
|
||||
let parsed: ClaudeSettings = serde_json::from_str(
|
||||
r#"{"env":{"ANTHROPIC_BASE_URL":"https://9router.example/v1","ANTHROPIC_API_KEY":"sk-test"}}"#,
|
||||
)
|
||||
.unwrap();
|
||||
let env = parsed.env.unwrap();
|
||||
assert_eq!(
|
||||
env.anthropic_base_url.as_deref(),
|
||||
Some("https://9router.example/v1")
|
||||
);
|
||||
assert_eq!(env.anthropic_api_key.as_deref(), Some("sk-test"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn apply_claude_refreshes_stale_provider_and_sets_opus_default() {
|
||||
// Simulate a previously-persisted app_config.json with a STALE claude
|
||||
// provider + non-opus default (e.g. user had switched provider).
|
||||
let mut cfg = AppConfig {
|
||||
providers: {
|
||||
let mut m = HashMap::new();
|
||||
m.insert(
|
||||
"claude".to_string(),
|
||||
claude_provider("https://old.example/v1", Some("sk-old")),
|
||||
);
|
||||
m
|
||||
},
|
||||
model_roles: HashMap::new(),
|
||||
default_provider: "router".to_string(),
|
||||
default_model: "other-model".to_string(),
|
||||
default_context_window: 256_000,
|
||||
};
|
||||
|
||||
// Detect returned a fresh provider from ~/.claude/settings.json.
|
||||
apply_claude_provider(
|
||||
&mut cfg,
|
||||
claude_provider("https://9router.example/v1", Some("sk-new")),
|
||||
None,
|
||||
);
|
||||
|
||||
let claude = cfg.providers.get("claude").unwrap();
|
||||
assert_eq!(claude.api_base, "https://9router.example/v1");
|
||||
assert_eq!(claude.default_api_key.as_deref(), Some("sk-new"));
|
||||
// Insert (not or_insert) → stale entry refreshed.
|
||||
assert_eq!(cfg.default_provider, "claude");
|
||||
assert_eq!(cfg.default_model, "claude-opus-5");
|
||||
|
||||
// Claude model roles registered.
|
||||
assert!(cfg.model_roles.contains_key("claude-opus-5"));
|
||||
assert!(cfg.model_roles.contains_key("claude-sonnet-5"));
|
||||
assert!(cfg.model_roles.contains_key("claude-haiku-4-5"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn apply_claude_honors_custom_model_from_settings() {
|
||||
let mut cfg = AppConfig::default();
|
||||
apply_claude_provider(
|
||||
&mut cfg,
|
||||
claude_provider("https://9router.example/v1", Some("sk-new")),
|
||||
Some("claude-opus-5".to_string()),
|
||||
);
|
||||
assert_eq!(cfg.default_model, "claude-opus-5");
|
||||
assert!(cfg.model_roles.contains_key("claude-opus-5"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn detect_uses_env_creds_as_fallback() {
|
||||
// When ~/.claude/settings.json is absent/unreadable, the env-var
|
||||
// fallback should produce a "claude" provider. Set env vars, call
|
||||
// detect, and assert the resulting provider uses them.
|
||||
std::env::set_var("ANTHROPIC_BASE_URL", "https://env.example/v1");
|
||||
std::env::set_var("ANTHROPIC_API_KEY", "sk-env");
|
||||
match detect_claude_settings_provider() {
|
||||
Some((provider, _custom)) => {
|
||||
// If the real settings.json exists it wins (base could be the
|
||||
// real 9router URL); otherwise env creds are used. Either way,
|
||||
// the provider must have api_key_env pointing at ANTHROPIC_API_KEY.
|
||||
assert_eq!(provider.api_key_env.as_deref(), Some("ANTHROPIC_API_KEY"));
|
||||
}
|
||||
None => {
|
||||
// No file + no env (shouldn't happen since we just set env).
|
||||
panic!("expected env fallback to produce a provider");
|
||||
}
|
||||
}
|
||||
std::env::remove_var("ANTHROPIC_BASE_URL");
|
||||
std::env::remove_var("ANTHROPIC_API_KEY");
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
//! Process-wide shared Tokio runtime for sync → async bridging.
|
||||
//!
|
||||
//! Many `Tool::run` implementations are synchronous but need to drive async
|
||||
//! work (LLM calls, subagent execution). Creating a fresh
|
||||
//! [`tokio::runtime::Runtime`] on every call is expensive (spawns a thread
|
||||
//! pool + runtime each time) and can fail randomly under thread pressure.
|
||||
//!
|
||||
//! # Flow
|
||||
//!
|
||||
//! [`runtime()`] returns a lazily-initialised process-wide runtime created
|
||||
//! exactly once via [`std::sync::OnceLock`]. Callers use
|
||||
//! `runtime().block_on(...)` exactly like they would with a local runtime —
|
||||
//! the only difference is the runtime is shared, so the cost is paid once per
|
||||
//! process instead of once per tool call.
|
||||
//!
|
||||
//! # Safety
|
||||
//!
|
||||
//! `block_on` panics if called from within a running Tokio runtime. The
|
||||
//! tools that use this helper are synchronous (`Tool::run`), so this is safe
|
||||
//! in practice. Async code should never call `runtime().block_on`.
|
||||
|
||||
use std::sync::OnceLock;
|
||||
|
||||
/// Maximum worker threads for the shared runtime. Kept modest — tools are
|
||||
/// mostly I/O-bound and rarely need more concurrency than this.
|
||||
const RUNTIME_WORKER_THREADS: usize = 8;
|
||||
|
||||
static SHARED_RUNTIME: OnceLock<tokio::runtime::Runtime> = OnceLock::new();
|
||||
|
||||
/// Return the process-wide shared Tokio runtime, initialising it on first use.
|
||||
///
|
||||
/// The runtime is configured with `worker_threads = 8` and
|
||||
/// `enable_all()` (time + IO drivers) so streams, timers, and network calls
|
||||
/// all work. If initialisation fails (extremely rare — resource exhaustion at
|
||||
/// startup), the process aborts with a clear message rather than returning
|
||||
/// an error on every subsequent call.
|
||||
pub fn runtime() -> &'static tokio::runtime::Runtime {
|
||||
SHARED_RUNTIME.get_or_init(|| {
|
||||
tokio::runtime::Builder::new_multi_thread()
|
||||
.worker_threads(RUNTIME_WORKER_THREADS)
|
||||
.thread_name("zesdex-shared-rt")
|
||||
.enable_all()
|
||||
.build()
|
||||
.expect("failed to create shared tokio runtime")
|
||||
})
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::runtime;
|
||||
|
||||
#[test]
|
||||
fn runtime_is_singleton() {
|
||||
assert!(std::ptr::eq(runtime(), runtime()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn runtime_blocks_and_resolves() {
|
||||
let val = runtime().block_on(async { 6 * 7 });
|
||||
assert_eq!(val, 42);
|
||||
}
|
||||
}
|
||||
@@ -23,6 +23,37 @@ use zesdex_domain::subagent_directive;
|
||||
/// Maximum number of tool-call iterations before the engine gives up.
|
||||
const MAX_ITERATIONS: u32 = 25;
|
||||
|
||||
/// A single tool-result message is truncated before entering the subagent's
|
||||
/// context so it cannot blow the window (matches the main turn service).
|
||||
const TOOL_OUTPUT_MAX_CHARS: usize = 12_000;
|
||||
|
||||
/// Maximum consecutive identical tool errors before the engine injects a
|
||||
/// recovery note steering the model to a different approach.
|
||||
const MAX_CONSECUTIVE_TOOL_ERRORS: usize = 3;
|
||||
|
||||
/// Pick a `max_tokens` budget proportional to the directive's length.
|
||||
fn adaptive_max_tokens(directive_len: usize) -> u32 {
|
||||
if directive_len <= 80 {
|
||||
800
|
||||
} else if directive_len <= 400 {
|
||||
1600
|
||||
} else {
|
||||
4096
|
||||
}
|
||||
}
|
||||
|
||||
fn truncate_tool_output(output: String) -> String {
|
||||
if output.len() <= TOOL_OUTPUT_MAX_CHARS {
|
||||
return output;
|
||||
}
|
||||
let mut result: String = output.chars().take(TOOL_OUTPUT_MAX_CHARS).collect();
|
||||
result.push_str(&format!(
|
||||
"\n...[truncated {} chars]",
|
||||
output.len() - TOOL_OUTPUT_MAX_CHARS
|
||||
));
|
||||
result
|
||||
}
|
||||
|
||||
/// Emit an `AgentProgress` event onto the turn-event queue, if one is
|
||||
/// configured in the `ToolCtx`.
|
||||
fn report_progress(tool_ctx: &ToolCtx, progress: AgentProgress) {
|
||||
@@ -85,11 +116,17 @@ pub async fn run_agent(
|
||||
Some(ctx.base_url.clone()),
|
||||
);
|
||||
|
||||
let max_tokens = adaptive_max_tokens(directive.len());
|
||||
|
||||
// Track repeated tool errors so the agent can recover from a dead end.
|
||||
let mut consecutive_errors = 0usize;
|
||||
let mut last_tool = String::new();
|
||||
|
||||
// Limited iteration loop so we don't run forever
|
||||
for iteration in 0..MAX_ITERATIONS {
|
||||
use zesdex_application::ports::ProviderService;
|
||||
let (response_msg, _usage) = client
|
||||
.chat(&messages, Some(defs.clone()), Some(4096), None)
|
||||
.chat(&messages, Some(defs.clone()), Some(max_tokens), Some(0.2))
|
||||
.await?;
|
||||
|
||||
let content = response_msg.content.clone().unwrap_or_default();
|
||||
@@ -113,7 +150,7 @@ pub async fn run_agent(
|
||||
&tool_ctx,
|
||||
AgentProgress::running(
|
||||
"subagent",
|
||||
format!("{}:{}", directive, tool_name),
|
||||
format!("{}:{tool_name}", directive),
|
||||
Some(tool_name.clone()),
|
||||
),
|
||||
);
|
||||
@@ -127,7 +164,29 @@ pub async fn run_agent(
|
||||
format!("Unknown tool: {tool_name}")
|
||||
};
|
||||
|
||||
messages.push(ChatMessage::tool(tc.id.clone(), result));
|
||||
// Error-recovery: if the same tool keeps failing, inject a
|
||||
// system note steering the model to a different approach.
|
||||
if result.starts_with("Error:") {
|
||||
if last_tool.as_str() == tool_name.as_str() {
|
||||
consecutive_errors += 1;
|
||||
} else {
|
||||
consecutive_errors = 1;
|
||||
last_tool = tool_name.to_string();
|
||||
}
|
||||
if consecutive_errors >= MAX_CONSECUTIVE_TOOL_ERRORS {
|
||||
messages.push(ChatMessage::system(
|
||||
zesdex_domain::agent::prompt::error_recovery_note(tool_name, &result),
|
||||
));
|
||||
consecutive_errors = 0;
|
||||
}
|
||||
} else {
|
||||
consecutive_errors = 0;
|
||||
}
|
||||
|
||||
messages.push(ChatMessage::tool(
|
||||
tc.id.clone(),
|
||||
truncate_tool_output(result),
|
||||
));
|
||||
}
|
||||
|
||||
// Add assistant response if there was text content
|
||||
|
||||
@@ -63,15 +63,21 @@ impl SubagentProvider {
|
||||
|
||||
/// Resolve subagent provider and model from settings.
|
||||
///
|
||||
/// Flow: reads `settings.provider` and `settings.model` → if model is empty,
|
||||
/// Flow: reads `settings.provider` and `settings.model` → if provider is
|
||||
/// empty, falls back to `app_config.default_provider` → if model is empty,
|
||||
/// falls back to the provider config's `default_model` → if that is also
|
||||
/// empty, uses the domain default model constant.
|
||||
/// empty, uses `app_config.default_model` → finally the domain default model
|
||||
/// constant.
|
||||
#[instrument]
|
||||
pub fn resolve_subagent_provider(
|
||||
settings: &zesdex_domain::cms::Settings,
|
||||
app_config: &zesdex_domain::cms::AppConfig,
|
||||
) -> (String, String) {
|
||||
let provider = settings.provider.clone();
|
||||
let provider = if settings.provider.is_empty() {
|
||||
app_config.default_provider.clone()
|
||||
} else {
|
||||
settings.provider.clone()
|
||||
};
|
||||
let model = settings.model.clone();
|
||||
|
||||
// Use the default model from the provider config if available
|
||||
@@ -80,6 +86,7 @@ pub fn resolve_subagent_provider(
|
||||
.providers
|
||||
.get(&provider)
|
||||
.and_then(|p| p.default_model.clone())
|
||||
.or_else(|| Some(app_config.default_model.clone()))
|
||||
.unwrap_or_else(|| zesdex_domain::agent::defaults::DEFAULT_MODEL.to_string())
|
||||
} else {
|
||||
model
|
||||
|
||||
@@ -32,7 +32,6 @@ pub fn spawn_subagent(
|
||||
) -> thread::JoinHandle<Result<String>> {
|
||||
info!("Spawning subagent: {directive}");
|
||||
thread::spawn(move || {
|
||||
let rt = tokio::runtime::Runtime::new()?;
|
||||
rt.block_on(run_agent(ctx, &directive, access, tool_ctx))
|
||||
crate::runtime::runtime().block_on(run_agent(ctx, &directive, access, tool_ctx))
|
||||
})
|
||||
}
|
||||
|
||||
@@ -15,6 +15,13 @@ impl InfrastructureToolExecutor {
|
||||
tools: all_tools(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Whether a tool is read-only and safe to execute concurrently with
|
||||
/// other parallel-safe tools. Delegates to the registry so the main
|
||||
/// turn loop and subagent engine share one source of truth.
|
||||
pub fn is_parallel_safe(tool_name: &str) -> bool {
|
||||
crate::tools::tool_is_parallel_safe(tool_name)
|
||||
}
|
||||
}
|
||||
|
||||
impl ToolExecutor for InfrastructureToolExecutor {
|
||||
@@ -37,4 +44,8 @@ impl ToolExecutor for InfrastructureToolExecutor {
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn is_parallel_safe(&self, tool_name: &str) -> bool {
|
||||
Self::is_parallel_safe(tool_name)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -59,7 +59,7 @@ pub mod workflow;
|
||||
// like `crate::tools::{Tool, ToolCtx}` continue to work.
|
||||
pub use context::{ToolCtx, ToolCtxBuilder};
|
||||
pub use graduated::{check_graduated_checks, GraduatedCheck};
|
||||
pub use registry::{all_tools, tool_defs, tool_is_risky};
|
||||
pub use registry::{all_tools, tool_defs, tool_is_parallel_safe, tool_is_risky};
|
||||
pub use util::{arg_str, execute_cmd, log_write_edit_tool, resolve_path};
|
||||
|
||||
/// Common interface every agent-invocable tool implements.
|
||||
|
||||
@@ -123,7 +123,7 @@ impl Tool for ParallelDelegate {
|
||||
.collect()
|
||||
} else {
|
||||
// Auto-split using LLM
|
||||
let rt = tokio::runtime::Runtime::new()?;
|
||||
let rt = crate::runtime::runtime();
|
||||
let directives = rt.block_on(auto_split_task(
|
||||
&task,
|
||||
max_parallel,
|
||||
@@ -146,9 +146,13 @@ impl Tool for ParallelDelegate {
|
||||
"parallel delegation: starting subagents"
|
||||
);
|
||||
|
||||
// Spawn agents in parallel
|
||||
let mut handles = Vec::new();
|
||||
for (i, (directive, access)) in directives.iter().enumerate() {
|
||||
// Spawn agents in parallel — bounded: never more than `max_parallel`
|
||||
// subagent threads in flight at once (Claude Code-style isolation).
|
||||
let mut results: Vec<(usize, String, String)> = Vec::new();
|
||||
for batch in directives.chunks(max_parallel) {
|
||||
let mut handles = Vec::with_capacity(batch.len());
|
||||
for (i, (directive, access)) in batch.iter().enumerate() {
|
||||
let global_idx = results.len() + i;
|
||||
let subagent_ctx = SubagentContext::new(
|
||||
directive.clone(),
|
||||
ctx.clone(),
|
||||
@@ -158,13 +162,12 @@ impl Tool for ParallelDelegate {
|
||||
model.clone(),
|
||||
);
|
||||
|
||||
debug!(agent_index = i, access = ?access, "spawning parallel agent");
|
||||
debug!(agent_index = global_idx, access = ?access, "spawning parallel agent");
|
||||
let handle = spawn_subagent(subagent_ctx, directive.clone(), *access, ctx.clone());
|
||||
handles.push((i, handle));
|
||||
handles.push((global_idx, handle));
|
||||
}
|
||||
|
||||
// Join all results
|
||||
let mut results: Vec<(usize, String, String)> = Vec::new();
|
||||
// Join this batch before spawning the next.
|
||||
for (i, handle) in handles {
|
||||
match handle.join() {
|
||||
Ok(Ok(output)) => {
|
||||
@@ -185,10 +188,11 @@ impl Tool for ParallelDelegate {
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Consolidate results
|
||||
if synthesize && results.len() > 1 {
|
||||
let rt = tokio::runtime::Runtime::new()?;
|
||||
let rt = crate::runtime::runtime();
|
||||
let consolidated =
|
||||
rt.block_on(consolidate_results(&results, &base_url, &api_key, &model))?;
|
||||
Ok(format!(
|
||||
|
||||
@@ -42,6 +42,7 @@ pub fn all_tools() -> Vec<Box<dyn super::Tool>> {
|
||||
// ── Best-practice tools (built-in) ─────────────────────────
|
||||
Box::new(super::best_practice::BestPractice),
|
||||
Box::new(super::best_practice::CommitConvention),
|
||||
Box::new(crate::best_practice::explore::ExploreCodebase),
|
||||
]
|
||||
}
|
||||
|
||||
@@ -51,6 +52,34 @@ pub fn tool_is_risky(name: &str) -> bool {
|
||||
matches!(name, "write" | "delete" | "edit" | "bash" | "git_operator")
|
||||
}
|
||||
|
||||
/// Whether a tool by name is read-only and therefore safe to run *in
|
||||
/// parallel* with other tool calls within the same assistant message.
|
||||
///
|
||||
/// Read-only tools only inspect the workspace (read files, grep, glob,
|
||||
/// semantic search, list symbols, recall memory, web search, directory
|
||||
/// listing). They have no side effects, so concurrent execution cannot
|
||||
/// create data races or conflicting writes.
|
||||
///
|
||||
/// Everything else (edits, writes, deletes, shell, git, planning, memory
|
||||
/// writes, agent/spawn orchestration) stays sequential to preserve
|
||||
/// correctness.
|
||||
pub fn tool_is_parallel_safe(name: &str) -> bool {
|
||||
matches!(
|
||||
name,
|
||||
"read"
|
||||
| "grep"
|
||||
| "glob"
|
||||
| "semantic_search"
|
||||
| "list_symbols"
|
||||
| "web_search"
|
||||
| "recall"
|
||||
| "dir_list"
|
||||
| "pong"
|
||||
| "seq_think"
|
||||
| "dir_cache_update"
|
||||
)
|
||||
}
|
||||
|
||||
/// Convert a list of tools into provider-facing `ToolDef` request schema.
|
||||
pub fn tool_defs(tools: &[Box<dyn super::Tool>]) -> Vec<zesdex_domain::core::ToolDef> {
|
||||
tools
|
||||
@@ -65,3 +94,59 @@ pub fn tool_defs(tools: &[Box<dyn super::Tool>]) -> Vec<zesdex_domain::core::Too
|
||||
})
|
||||
.collect()
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn read_only_tools_are_parallel_safe() {
|
||||
for name in [
|
||||
"read",
|
||||
"grep",
|
||||
"glob",
|
||||
"semantic_search",
|
||||
"list_symbols",
|
||||
"web_search",
|
||||
"recall",
|
||||
"dir_list",
|
||||
"pong",
|
||||
"seq_think",
|
||||
"dir_cache_update",
|
||||
] {
|
||||
assert!(
|
||||
tool_is_parallel_safe(name),
|
||||
"{name} should be parallel-safe"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn mutating_and_shell_tools_are_not_parallel_safe() {
|
||||
for name in [
|
||||
"edit",
|
||||
"write",
|
||||
"delete",
|
||||
"bash",
|
||||
"git_operator",
|
||||
"git_worktree",
|
||||
"remember",
|
||||
"forget",
|
||||
"todowrite",
|
||||
"todofinish",
|
||||
"plan_enter",
|
||||
"plan_ready",
|
||||
"workflow_run",
|
||||
"hive_mind",
|
||||
"spawn_agents",
|
||||
"spawn_pipeline",
|
||||
"parallel_delegate",
|
||||
"explore_codebase",
|
||||
] {
|
||||
assert!(
|
||||
!tool_is_parallel_safe(name),
|
||||
"{name} should NOT be parallel-safe"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -63,7 +63,7 @@ impl crate::tools::Tool for DirCacheUpdate {
|
||||
// Persist the resolved paths into the shared DirCache so the TUI
|
||||
// and other tools can read the cached listing without re-scanning.
|
||||
let dc = ctx.dir_cache.clone();
|
||||
let rt = tokio::runtime::Runtime::new()?;
|
||||
let rt = crate::runtime::runtime();
|
||||
rt.block_on(async { dc.write().await.set(resolved).await });
|
||||
|
||||
info!(count, "directory cache updated");
|
||||
|
||||
@@ -65,7 +65,7 @@ impl Tool for WorkflowRun {
|
||||
zesdex_domain::agent::defaults::DEFAULT_MODEL.to_string(),
|
||||
None,
|
||||
);
|
||||
let rt = tokio::runtime::Runtime::new()?;
|
||||
let rt = crate::runtime::runtime();
|
||||
let result: Vec<String> =
|
||||
rt.block_on(async { execute_workflow(&script, ctx, &llm_client).await })?;
|
||||
|
||||
@@ -229,7 +229,7 @@ impl Tool for HiveMind {
|
||||
.ok_or_else(|| anyhow::anyhow!("missing 'cycles' array"))?;
|
||||
|
||||
info!("Hive mind starting with {} cycles", cycles_val.len());
|
||||
let rt = tokio::runtime::Runtime::new()?;
|
||||
let rt = crate::runtime::runtime();
|
||||
let mut all_node_outputs = Vec::new();
|
||||
|
||||
for (cycle_idx, cycle_val) in cycles_val.iter().enumerate() {
|
||||
|
||||
@@ -1,11 +1,15 @@
|
||||
//! Hive-mind cycle execution — run one cycle of parallel nodes.
|
||||
//!
|
||||
//! Flow: load settings → resolve LLM credentials → run all directives in the
|
||||
//! cycle concurrently via try_join_all → collect Vec<NodeOutput>.
|
||||
//! cycle concurrently via a BOUNDED buffer (`buffer_unordered(MAX)`) → collect
|
||||
//! `Vec<NodeOutput>`. Unlike `try_join_all`, a single failing node does NOT
|
||||
//! fail the whole cycle — failed nodes are logged and replaced with an
|
||||
//! `[ERROR]` output so the remaining results are preserved (like Claude
|
||||
//! Code's isolated subagents).
|
||||
|
||||
use anyhow::Result;
|
||||
use futures_util::future::try_join_all;
|
||||
use tracing::info;
|
||||
use futures_util::stream::StreamExt;
|
||||
use tracing::{info, warn};
|
||||
|
||||
use zesdex_domain::cms::{AppConfigRepository, SettingsRepository};
|
||||
use zesdex_domain::core::Store;
|
||||
@@ -15,16 +19,21 @@ use crate::subagent::context::SubagentContext;
|
||||
use crate::subagent::division::AccessTier;
|
||||
use crate::subagent::engine::run_agent;
|
||||
use crate::tools::ToolCtx;
|
||||
use zesdex_domain::workflow::{CognitiveCycle, NodeOutput};
|
||||
use zesdex_domain::workflow::{CognitiveCycle, NodeDirective, NodeOutput};
|
||||
|
||||
/// Maximum number of hive-mind nodes running concurrently per cycle.
|
||||
/// Keeps thread/runtime pressure bounded (Claude Code-style).
|
||||
const MAX_CONCURRENT_NODES: usize = 8;
|
||||
|
||||
/// Execute one cycle: run each node directive and collect outputs.
|
||||
///
|
||||
/// Flow:
|
||||
/// 1. Load `Settings` and `AppConfig` from the store directory.
|
||||
/// 2. Resolve provider, model, base_url, and api_key.
|
||||
/// 3. Spawn all directives concurrently — each builds a `SubagentContext`
|
||||
/// and calls `run_agent` (Full access).
|
||||
/// 4. `try_join_all` waits for all to complete, then collect `NodeOutput`s.
|
||||
/// 3. Spawn directives with bounded concurrency — each builds a
|
||||
/// `SubagentContext` and calls `run_agent`.
|
||||
/// 4. Collect `NodeOutput`s; failed nodes are logged and replaced with an
|
||||
/// `[ERROR]` placeholder so the cycle still completes.
|
||||
pub async fn execute_cycle(cycle: &CognitiveCycle, tool_ctx: &ToolCtx) -> Result<Vec<NodeOutput>> {
|
||||
info!(
|
||||
"Executing cycle {} with {} directives",
|
||||
@@ -53,10 +62,9 @@ pub async fn execute_cycle(cycle: &CognitiveCycle, tool_ctx: &ToolCtx) -> Result
|
||||
|
||||
let cycle_index = cycle.index;
|
||||
|
||||
use zesdex_domain::workflow::NodeDirective;
|
||||
|
||||
// Run all directives in this cycle concurrently.
|
||||
let handles: Vec<_> = cycle
|
||||
// Run all directives with bounded concurrency. Each node is its own
|
||||
// future; failures are collected, not propagated (isolated errors).
|
||||
let tasks: Vec<_> = cycle
|
||||
.directives
|
||||
.iter()
|
||||
.enumerate()
|
||||
@@ -79,18 +87,33 @@ pub async fn execute_cycle(cycle: &CognitiveCycle, tool_ctx: &ToolCtx) -> Result
|
||||
_ => AccessTier::Read,
|
||||
};
|
||||
|
||||
let node_id = format!("Node-{}-{}", cycle_index, i);
|
||||
async move {
|
||||
let result = run_agent(ctx, &dir, access, tc).await?;
|
||||
Ok::<NodeOutput, anyhow::Error>(NodeOutput {
|
||||
id: format!("Node-{}-{}", cycle_index, i),
|
||||
match run_agent(ctx, &dir, access, tc).await {
|
||||
Ok(output) => Ok::<NodeOutput, anyhow::Error>(NodeOutput {
|
||||
id: node_id.clone(),
|
||||
directive: dir,
|
||||
output: result,
|
||||
output,
|
||||
}),
|
||||
Err(e) => {
|
||||
warn!(node = %node_id, error = %e, "hive-mind node failed (isolated)");
|
||||
Ok::<NodeOutput, anyhow::Error>(NodeOutput {
|
||||
id: node_id,
|
||||
directive: dir,
|
||||
output: format!("[ERROR] {e}"),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
.collect();
|
||||
|
||||
let results = try_join_all(handles).await?;
|
||||
// Bounded concurrency: run at most MAX_CONCURRENT_NODES futures at once.
|
||||
let mut stream = futures_util::stream::iter(tasks).buffer_unordered(MAX_CONCURRENT_NODES);
|
||||
let mut results = Vec::with_capacity(cycle.directives.len());
|
||||
while let Some(node) = stream.next().await {
|
||||
results.push(node?);
|
||||
}
|
||||
|
||||
Ok(results)
|
||||
}
|
||||
|
||||
@@ -316,13 +316,13 @@ fn handle_submit_input(state: &mut AppStateRest, text: String) {
|
||||
in_flight: std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)),
|
||||
abort: state.abort_flag.clone(),
|
||||
api_key: api_key.clone(),
|
||||
model: state.settings.model.clone(),
|
||||
model: zesdex_domain::cms::resolve_effective_model(&state.settings, &state.app_config),
|
||||
api_base: provider_cfg.as_ref().map(|cfg| cfg.api_base.clone()),
|
||||
};
|
||||
|
||||
let client = std::sync::Arc::new(zesdex_infrastructure::llm::provider::LlmClient::new(
|
||||
api_key,
|
||||
state.settings.model.clone(),
|
||||
zesdex_domain::cms::resolve_effective_model(&state.settings, &state.app_config),
|
||||
provider_cfg.map(|cfg| cfg.api_base.clone()),
|
||||
));
|
||||
|
||||
@@ -465,14 +465,13 @@ fn handle_compact(state: &mut AppStateRest) {
|
||||
.get(provider_name)
|
||||
.cloned()
|
||||
.unwrap_or_default();
|
||||
let model = state.settings.model.clone();
|
||||
let model = zesdex_domain::cms::resolve_effective_model(&state.settings, &state.app_config);
|
||||
let api_base = provider_cfg.map(|cfg| cfg.api_base.clone());
|
||||
|
||||
let client = zesdex_infrastructure::llm::provider::LlmClient::new(api_key, model, api_base);
|
||||
|
||||
if let Some(ref mut rt) = state.session_runtime {
|
||||
let tokio_rt =
|
||||
tokio::runtime::Runtime::new().expect("create tokio runtime for AI compaction");
|
||||
let tokio_rt = zesdex_infrastructure::runtime::runtime();
|
||||
if let Ok(()) = tokio_rt.block_on(
|
||||
zesdex_application::agent::turn_service::compact_messages_with_ai(
|
||||
&mut rt.messages,
|
||||
|
||||
@@ -80,7 +80,7 @@ pub fn spawn_agent_turn(state: &mut AppStateRest, text: String) {
|
||||
// ── Resolve provider configuration ─────────────────────────────────
|
||||
let provider_name = &state.settings.provider;
|
||||
let api_key = resolve_api_key(state, provider_name);
|
||||
let model = state.settings.model.clone();
|
||||
let model = zesdex_domain::cms::resolve_effective_model(&state.settings, &state.app_config);
|
||||
let api_base = resolve_api_base(state, provider_name);
|
||||
|
||||
// ── Build message list ─────────────────────────────────────────────
|
||||
@@ -110,13 +110,6 @@ pub fn spawn_agent_turn(state: &mut AppStateRest, text: String) {
|
||||
api_base: api_base.clone(),
|
||||
};
|
||||
|
||||
// Clone credentials before moving into LlmClient.
|
||||
let explore_api_key = api_key.clone();
|
||||
let explore_model = model.clone();
|
||||
let explore_base_url = api_base
|
||||
.clone()
|
||||
.unwrap_or_else(|| "https://api.openai.com/v1".to_string());
|
||||
|
||||
let client = std::sync::Arc::new(LlmClient::new(api_key, model, api_base));
|
||||
|
||||
let tool_ctx = ToolCtx::builder()
|
||||
@@ -125,29 +118,12 @@ pub fn spawn_agent_turn(state: &mut AppStateRest, text: String) {
|
||||
.turn_events(turn_events)
|
||||
.build();
|
||||
|
||||
// Clone ToolCtx for the explore service (before moving into executor).
|
||||
let explore_ctx = tool_ctx.clone();
|
||||
|
||||
let tool_executor = std::sync::Arc::new(InfrastructureToolExecutor::new(tool_ctx));
|
||||
|
||||
let tools = all_tools();
|
||||
let defs = tool_defs(&tools);
|
||||
|
||||
// Wire the mandatory explore phase (3+ parallel subagents).
|
||||
let explore_creds = zesdex_infrastructure::best_practice::explore::Credentials {
|
||||
base_url: explore_base_url,
|
||||
api_key: explore_api_key,
|
||||
model: explore_model,
|
||||
};
|
||||
let explore_service = std::sync::Arc::new(
|
||||
zesdex_infrastructure::best_practice::explore::ExploreServiceImpl::new(
|
||||
explore_ctx,
|
||||
explore_creds,
|
||||
),
|
||||
);
|
||||
|
||||
let turn_service =
|
||||
AgentTurnServiceImpl::new(client, tool_executor, defs).with_explore(explore_service);
|
||||
let turn_service = AgentTurnServiceImpl::new(client, tool_executor, defs);
|
||||
|
||||
tokio::spawn(async move {
|
||||
let _ = turn_service.run_turn(params).await;
|
||||
|
||||
Reference in New Issue
Block a user