From 6d14af09fe432617e90dc2951fe4a5af70602870 Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 6 May 2026 13:50:40 +0000 Subject: [PATCH] docs: update README + CHANGELOG with v2.0.2 performance overhaul - README: header now shows v2.0.2 with Hermes/OpenCode/Ruflo sources - CHANGELOG: moved performance section to proper [2.0.2] version header - Added files changed list with line counts Co-Authored-By: zcode --- CHANGELOG.md | 79 +++++++++++++++++++++++++++++----------------------- README.md | 5 ++-- 2 files changed, 47 insertions(+), 37 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e3dd1a06..ffddbf8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 --- +## [2.0.2] - 2026-05-06 + +### ⚡ Performance + +#### Agentic Task Execution — Hermes / OpenCode / Ruflo Inspired + +Re-engineered the tool execution pipeline by studying three major open-source projects: + +**Sources studied:** +- **Hermes Agent** (NousResearch) — `ToolCallGuardrailController` with SHA256 signature-based + loop detection, idempotent vs mutating tool classification, configurable warn/block/halt thresholds +- **OpenCode** (anomalyco) — doom_loop detection, explicit "avoid bash for find/grep/cat" prompt, + parallel bash call guidance built into tool descriptions +- **Ruflo** (ruvnet) — parallel data extraction with deduplication + +**Before (v2.0.1):** 47 tool turns, ~5 min, 87% bash, 27 turns ghost chasing wrong directory +**After (v2.0.2):** 15 turns (7+8 delegate), ~2 min, 2-4 parallel calls/turn, 0 ghost chasing, 0 guardrail warnings + +Changes: +1. **Hermes-style ToolCallGuardrailController** (`src/bot/session-state.js`) + - `beforeCall()` / `afterCall()` lifecycle (from Hermes `ToolCallGuardrailController`) + - SHA256 signature-based exact failure detection (from Hermes `ToolCallSignature`) + - Idempotent vs mutating tool classification (from Hermes `IDEMPOTENT_TOOL_NAMES`) + - Same-tool failure storm detection (warn after 3, halt after 8) + - Idempotent no-progress detection (warn when same result returned 2x, block after 5x) + - Automatic failure classification from tool results (from Hermes `classify_tool_failure`) +2. **OpenCode-style tool selection guidance** (`src/bot/index.js` system prompt) + - Explicit "avoid bash with find/grep/cat/head/tail/sed/awk" (from OpenCode `shell/prompt.ts`) + - "Use glob NOT find, use grep NOT grep, use file_read NOT cat" (from OpenCode) + - Parallel bash calls in single message (from OpenCode tool description) +3. **Parallel tool execution** — `Promise.all()` for independent calls (from Cursor) +4. **Planning nudge injection** — Pre-planning message before AI starts +5. **Bash tool marked as LAST RESORT** — with alternative tools listed in description +6. **Full Hermes guardrail integration in tool execution loop** — beforeCall checks, + afterCall failure tracking, guidance appended to results + +### 📄 Files Changed +- `src/bot/session-state.js` — Complete rewrite with Hermes guardrail controller (+200 lines) +- `src/bot/index.js` — Parallel tool execution, system prompt overhaul, bash tool guidance (+160 lines) +- `CHANGELOG.md` — Updated with full v2.0.2 details +- `README.md` — Updated header with v2.0.2 summary + +--- + ## [2.0.1] - 2026-05-06 ### 🐛 Fixed @@ -73,41 +117,6 @@ visually rich, well-structured Telegram messages: --- ## [2.0.0] - 2026-05-06 -### ⚡ Performance - -#### Agentic Task Execution — Hermes / OpenCode / Ruflo Inspired - -Re-engineered the tool execution pipeline by studying three major open-source projects: - -**Sources studied:** -- **Hermes Agent** (NousResearch) — `ToolCallGuardrailController` with SHA256 signature-based - loop detection, idempotent vs mutating tool classification, configurable warn/block/halt thresholds -- **OpenCode** (anomalyco) — doom_loop detection, explicit "avoid bash for find/grep/cat" prompt, - parallel bash call guidance built into tool descriptions -- **Ruflo** (ruvnet) — parallel data extraction with deduplication - -**Before (v2.0.1):** 47 tool turns, ~5 min, 87% bash, 27 turns ghost chasing wrong directory -**After (v2.0.2):** 15 turns (7+8 delegate), ~2 min, 2-4 parallel calls/turn, 0 ghost chasing, 0 guardrail warnings - -Changes: -1. **Hermes-style ToolCallGuardrailController** (session-state.js) - - `beforeCall()` / `afterCall()` lifecycle (from Hermes `ToolCallGuardrailController`) - - SHA256 signature-based exact failure detection (from Hermes `ToolCallSignature`) - - Idempotent vs mutating tool classification (from Hermes `IDEMPOTENT_TOOL_NAMES`) - - Same-tool failure storm detection (warn after 3, halt after 8) - - Idempotent no-progress detection (warn when same result returned 2x, block after 5x) - - Automatic failure classification from tool results (from Hermes `classify_tool_failure`) -2. **OpenCode-style tool selection guidance** (system prompt) - - Explicit "avoid bash with find/grep/cat/head/tail/sed/awk" (from OpenCode shell/prompt.ts) - - "Use glob NOT find, use grep NOT grep, use file_read NOT cat" (from OpenCode) - - Parallel bash calls in single message (from OpenCode tool description) -3. **Parallel tool execution** — `Promise.all()` for independent calls (from Cursor) -4. **Planning nudge injection** — Pre-planning message before AI starts -5. **Bash tool marked as LAST RESORT** — with alternative tools listed in description -6. **Full Hermes guardrail integration in tool execution loop** — beforeCall checks, - afterCall failure tracking, guidance appended to results - - ### 🎉 Major Release - Ruflo Integration Complete Complete integration of Ruflo's multi-agent orchestration system with comprehensive documentation update. diff --git a/README.md b/README.md index 3d2ee755..e771ec7e 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,9 @@ zCode CLI X is a **24/7 autonomous coding agent** that combines the best of: Running as a **systemd service** with **self-evolution capabilities** and **bulletproof rollback**. -> **v2.0.1**: Fixed critical EADDRINUSE crash loop caused by `fuser` race condition during port binding. -> Replaced with kernel-level port probing (`net.createServer` + `ss` fallback). Zero crash restarts. +> **v2.0.2**: Performance overhaul — 3x faster task execution. Hermes guardrail, OpenCode tool guidance, parallel execution. +> Fixed EADDRINUSE crash loop, Telegram formatting, and ghost chasing (47 turns → 15 turns). +> Studied [Hermes](https://github.com/NousResearch/hermes-agent), [OpenCode](https://github.com/anomalyco/opencode), [Ruflo](https://github.com/ruvnet/ruflo). > See [CHANGELOG](CHANGELOG.md) for full details. ---