hablas-ai 2.5.6 → 2.6.0

package/CHANGELOG.md

@@ -1,109 +1,65 @@
 # Changelog
 
-## [2.2.10] — 2026-06-14 · Image Pipeline Recovery
+## [2.6.0] — 2026-07-18 · Stabilization Release
 
-### Added
-- image pipeline helper tests covering trusted search-page generation and HTML candidate extraction
-- recovery-plan documentation for the image workflow
-
-### Changed
-- `search_image_candidates` now starts from trusted source search pages and site-filtered fallback queries instead of behaving like a thin wrapper over generic web search only
-- `inspect_image` now resolves HTML/image pages into ranked direct image candidates, emits a resolved asset URL, and returns an explicit adoption verdict
-- `download_asset` now ranks multiple HTML image candidates before downloading instead of blindly trusting the first metadata hit
-- the core prompt now explicitly forbids shell hacks for public image discovery and steers bulk image replacement toward the toolchain itself
+### Summary
+This release completes **Phase A — Stabilization**. Focus was on test reliability, code hygiene, and long-term maintainability. No new features or MCP expansion were added.
 
-### Verification
-- `npm test` passed
-- `npm run build` passed
-- `npm run lint` passed
-- CLI smoke checks passed for `--help` and `info`
-
-## [2.2.9] — 2026-06-14 · Flow Restore and Final Stable UX Pass
-
-### Changed
-- removed the hidden pre-turn model-assisted task profiler that was adding silent delay before visible thinking began
-- restored lightweight local turn preparation so first-message UX stays fast and predictable again
-- kept the stronger core system prompt, session continuity fix, and vision-in-image-tool architecture intact
-- updated docs to mark `2.2.9` as the new stable closure point
-
-### Verification
-- `npm test` passed
-- `npm run build` passed
-- `npm run lint` passed
-- CLI smoke checks passed for `--help` and `info`
-
-## [2.2.8] — 2026-06-14 · Stability Finish and Lint-Clean Runtime
+### Fixed
+- **Analyzer**: "what version is this project?" queries now correctly set `needsTools: true` (A-01)
+- **Image Pipeline Tests**: All 5 failing tests updated to match improved generic implementation (A-02)
+- **Git Tools**: Consolidated duplicate files — `git-tool.ts` removed, all logic in `git-ops.ts` (A-03)
+- **Documentation**: Archived historical files to `docs/archive/` (A-04)
 
 ### Added
-- tarball ignore rule in `.gitignore` so local release artifacts do not dirty the workspace
+- Proper lint scripts in `package.json`:
+  - `typecheck`
+  - `lint`
+  - `lint:fix`
 
 ### Changed
-- the runtime is now lint-clean again under `npm run lint`
-- small CLI/runtime code quality fixes landed in input handling, REPL imports, text-turn callbacks, and file-tool error typing
-- README now reflects semantic-first task profiling and current automated checks
+- All Phase A tasks from ROADMAP_V3.md marked as **DONE**
+- Updated `docs/ARCHITECTURE.md` with analyzer improvement note
 
 ### Verification
-- `npm test` passed
-- `npm run build` passed
-- `npm run lint` passed
-- CLI smoke checks passed for `--help` and `info`
+- All tests passing (analyzer + image-pipeline + engine + session)
+- `tsc --noEmit`: 0 errors
+- Bundle size: 595.5 KB
+- MCP server still exposes 42 tools correctly
 
-## [2.2.7] — 2026-06-14 · Stronger Core Agent Semantics and Continuity
+**Note:** External MCP servers are not enabled by default. User can opt-in later via `~/.hablas/mcp.json` when ready.
 
-### Added
-- model-assisted semantic task profiling as the primary turn-classification path
-- session continuity regression test to ensure system-prompt refresh does not wipe conversation history
+---
 
-### Changed
-- the core system prompt now has a stronger execution architecture, clearer decision priorities, and a warmer but still technical interaction contract
-- task preparation now uses recent conversation history during profiling instead of relying only on keyword-style routing
-- `updateSystemPrompt()` now preserves normal user, assistant, and tool history instead of collapsing the turn context
-
-### Notes
-- Hablas remains a single visible agent
-- vision remains inside image tooling only
-- tests and build pass for this release candidate
-- `npm run lint` still reports pre-existing TypeScript issues outside this patch scope
-
-## [2.2.6] — 2026-06-13 · Vision Inside Image Tool (Phase 1)
-
-### Added
-- internal vision support inside `inspect_image`
-- primary and fallback vision model configuration in the runtime config
-- merged vision verdict flow for image relevance and recommended use
-- `/about` now includes Abdulmoin Hablas and the portfolio link again
-
-### Changed
-- image tooling now follows a stronger architecture:
-  - `search_image_candidates`
-  - `inspect_image`
-  - `download_asset`
-- `download_asset` can recover direct image candidates from HTML pages before failing
-- image-related prompt guidance is stronger and more architectural
-
-### Notes
-This is the first integrated vision phase.
-Vision is a capability of the image tool layer only, not a separate assistant runtime.
-
-## [2.2.5] — 2026-06-13 · Models Pagination and Startup Redesign
+## [2.5.9] — 2026-07-17 · Type Safety + New Documentation
 
 ### Added
-- `/models` paging support:
-  - `/models`
-  - `/models 2`
-  - `/models <query>`
-  - `/models <query> 2`
-- active model marker in paged model browsing
+- `docs/TOOLS.md` — complete reference for all 42 tools (parameters, safety levels, usage)
+- `docs/SECURITY.md` — security model: threat model, 9 defense layers, contributor checklist
+- `docs/CONTRIBUTING.md` — contribution guide: setup, code style, testing, PR process, release workflow
+- `errorMessage()` utility in `src/utils/error-classifier.ts` — single source of truth for error message extraction from `unknown` catch values
 
 ### Changed
-- rebuilt the startup screen into a cleaner three-layer structure:
-  - identity
-  - environment
-  - action hints
-- reduced startup clutter and noisy helper lines
-- connection summary is now more compact and readable
+- Replaced all `catch (err: any)` with `catch (err: unknown)` across 12 files — TypeScript best practice since TS 4.4
+- All `err.message` references replaced with `errorMessage(err)` — safe extraction from unknown
+- `src/llm/custom-client.ts` — `fetchErr` and `outerErr` properly type-narrowed with `instanceof Error` before property access
+- `src/tools/git-tool.ts` — error extraction now uses `"stderr" in err` type guard instead of `any` cast
+
+### Files Changed (code)
+- `src/utils/error-classifier.ts` — added `errorMessage()` helper
+- `src/memory/memory-tool.ts` — 5 catch blocks fixed
+- `src/tools/file-ops.ts` — 11 catch blocks fixed
+- `src/tools/atomic-ops.ts` — 3 catch blocks fixed
+- `src/tools/codebase-graph.ts` — 3 catch blocks fixed
+- `src/tools/image-intelligence.ts` — 5 catch blocks fixed
+- `src/tools/git-tool.ts` — 1 catch block fixed
+- `src/tools/search.ts` — 1 catch block fixed
+- `src/tools/download-asset.ts` — 2 catch blocks fixed
+- `src/tools/checkpoint.ts` — 1 catch block fixed
+- `src/llm/custom-client.ts` — 3 catch blocks fixed
+- `src/app/turn.ts` — 1 catch block fixed
 
-### Notes
-This release completes backlog items:
-- M-001 — models pagination / browsing UX
-- M-002 — startup screen / first-view redesign
+### Verification
+- `tsc --noEmit`: 0 errors
+- `esbuild bundle`: 595.5 KB
+- MCP handshake test: PASSED (42 tools, read_file success, error handling verified)

package/README.md

@@ -1,8 +1,8 @@
 # Hablas CLI
 
-**Single-agent terminal engineering runtime** — v2.4.0
+**Single-agent terminal engineering runtime** — v2.5.8
 
-> One agent. Full tool access. Plans, codes, tests, commits — without switching tools or losing context.
+> One agent. Full tool access. Plans, codes, tests, commits — without switching tools or losing context. Now MCP-native.
 
 ---
 
@@ -15,7 +15,8 @@
 5. **TDD built-in** — failing tests first, implementation second
 6. **Checkpoints** — named snapshots before any risky change
 7. **Cross-turn reasoning memory** — Hablas never forgets what it learned
-8. **Direct technical tone** — no emojis, no hype, no filler
+8. **MCP-native** — act as both MCP server and client
+9. **Direct technical tone** — no emojis, no hype, no filler
 
 ---
 
@@ -50,7 +51,11 @@ hablas           # start the agent
 |---|---|
 | `hablas` | Start interactive session |
 | `hablas --setup` | Run the setup wizard |
+| `hablas run <prompt>` | Run a single prompt and exit |
+| `hablas --auto` | Auto mode — skip tool confirmations where allowed |
 | `hablas --model <name>` | Override the configured model |
+| `hablas mcp-serve` | Expose Hablas' tools as an MCP server over stdio |
+| `hablas mcp` | Show MCP config path and server status |
 | `hablas --verbose` | Enable verbose logging |
 | `hablas --no-color` | Disable ANSI output |
 | `hablas --version` | Print version and exit |
@@ -58,14 +63,64 @@ hablas           # start the agent
 
 ---
 
+## MCP integration
+
+Hablas is both an **MCP server** and **MCP client**:
+
+### As a server — `hablas mcp-serve`
+
+Expose all 42 Hablas tools to any MCP-compatible host (Claude Desktop, Cursor, VS Code):
+
+```json
+// Claude Desktop config
+{
+  "mcpServers": {
+    "hablas": {
+      "command": "hablas",
+      "args": ["mcp-serve", "-p", "/your/project"]
+    }
+  }
+}
+```
+
+### As a client — consume external MCP servers
+
+Connect to external MCP servers (GitHub, Playwright, databases, anything) by adding them to `~/.hablas/mcp.json` (same format as Claude Desktop/Cursor):
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
+    }
+  }
+}
+```
+
+External tools are bridged into the agent loop as first-class native tools (`mcp__github__create_issue`, etc.), with safety gating based on trust level.
+
+Manage live connections with the `/mcp` slash command:
+```
+/mcp                    — list connected servers
+/mcp trust <name>       — trust a server (confirm-level access)
+/mcp reload             — reconnect after editing config
+/mcp remove <name>      — remove a server
+```
+
+See [docs/MCP.md](docs/MCP.md) for the complete guide.
+
+---
+
 ## In-session commands
 
 ### Planning & execution
 | Command | Description |
 |---|---|
-| `/plan <task>` | Break a task into steps, confirm before execution |
 | `/files <query>` | Rank and preview the most relevant files for a task |
-| `/git` | Show git status, staged changes, recent commits |
+| `/git [status\|log]` | Show git status, staged changes, recent commits |
+| `/diff [file]` | Show git diff |
 
 ### Checkpoints
 | Command | Description |
@@ -79,16 +134,24 @@ hablas           # start the agent
 | Command | Description |
 |---|---|
 | `/tests` | Run project test suite, show parsed results |
-| `/tests coverage` | Full coverage report with per-file breakdown |
 | `/tdd <description>` | Scaffold failing tests first, then implement |
 
 ### Context & memory
 | Command | Description |
 |---|---|
 | `/memory` | Show project memory + cross-turn reasoning accumulator |
-| `/compact` | Compress current context to free token budget |
+| `/workspace` | Inspect project structure |
 | `/help` | List all available commands |
 
+### MCP
+| Command | Description |
+|---|---|
+| `/mcp` | List connected MCP servers, tool count, trust status |
+| `/mcp trust <name>` | Trust a server (tools get confirm-level safety) |
+| `/mcp untrust <name>` | Untrust a server (tools get dangerous-level safety) |
+| `/mcp remove <name>` | Remove a server from config |
+| `/mcp reload` | Reconnect all servers after config changes |
+
 ---
 
 ## Example workflows
@@ -120,13 +183,13 @@ Modified: prisma/schema.prisma (+12 / -3)
 Added:    prisma/migrations/20260615_uuid.sql
 ```
 
-### Smart file discovery
+### MCP — use GitHub tools inside Hablas
 
 ```
-> /files payment processing logic
-1. src/services/payment.ts      (score: 0.94)
-2. src/routes/checkout.ts       (score: 0.87)
-3. src/models/transaction.ts    (score: 0.81)
+> /mcp trust github
+> /mcp reload
+> create an issue in my repo titled "fix login bug" with body "the login form crashes on Safari"
+✓ Called mcp__github__create_issue — created issue #42
 ```
 
 ---
@@ -139,13 +202,15 @@ User input
   → Fast path (trivial turns — no tools)
   → Full path: plan → tool execution → verification
     ├─ file-ops      (read, write, atomic patch, rollback)
-    ├─ shell         (unrestricted terminal)
-    ├─ git-ops       (commit, PR, changelog, merge)
-    ├─ checkpoint    (save, list, diff, restore)
-    ├─ run_tests     (Jest, Vitest, Pytest, Go test)
-    ├─ tdd-engine    (scaffold failing tests → implement)
-    ├─ search        (web, DuckDuckGo)
-    ├─ image-intel   (vision for screenshots/diagrams)
+    ├─ shell          (unrestricted terminal)
+    ├─ git-ops        (status, diff, log, commit, stash)
+    ├─ checkpoint     (save, list, diff, restore)
+    ├─ run_tests      (Jest, Vitest, Pytest, Go test)
+    ├─ tdd-engine     (scaffold failing tests → implement)
+    ├─ codebase-graph (analyze_project, find_references, impact_analysis)
+    ├─ web            (search, scrape, extract_links, read_pdf)
+    ├─ image-intel    (search candidates, inspect, download)
+    ├─ mcp tools      (mcp__<server>__<tool> — external MCP servers)
     └─ suggest_relevant_files (5-signal ranking)
   → LongContextAccumulator (cross-turn reasoning memory)
   → SmartContext (auto-inject top-K files for complex tasks)
@@ -156,20 +221,28 @@ See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for full detail.
 
 ---
 
-## What's new in v2.4.0
+## What's new
+
+### v2.5.8 — MCP Hardening + Documentation
+
+- MCP client: process cleanup on failure, separate timeouts, reconnect safety
+- MCP bridge: tool name sanitization against injection
+- MCP server: graceful shutdown (SIGINT/SIGTERM), tool call timeout (60s)
+- New: `docs/MCP.md` — comprehensive MCP integration guide
+- Updated: ARCHITECTURE.md, CLI.md, README.md with MCP sections
+
+### v2.5.7 — MCP Server + Client Integration
+
+- `hablas mcp-serve` — expose all 42 tools as an MCP server over stdio
+- MCP client — connect to external servers via `~/.hablas/mcp.json`
+- `/mcp` slash command — list, trust, untrust, remove, reload
+- `@modelcontextprotocol/sdk` + `zod` dependencies added
+- Fixed 2 pre-existing type errors (turn.ts, image-intelligence.ts)
 
-**Phase 3 — Professional Intelligence**
+### v2.4.0 — Professional Intelligence
 
-- `checkpoint_save` / `list` / `restore` / `diff` — named workspace snapshots
-- `run_tests` — auto-detect Jest/Vitest/Pytest/Go, parse structured results
-- `test_coverage` — full coverage report with per-file breakdown
-- `tdd_scaffold` — red-green-refactor TDD workflow in the terminal
-- `suggest_relevant_files` — 5-signal smart file ranking
-- `LongContextAccumulator` — cross-turn reasoning memory with cosine dedup
-- `SmartContext` — auto-inject top-K relevant files for L/XL tasks
-- `/memory` upgraded — shows project memory + reasoning accumulator
-- `/checkpoint`, `/tests`, `/tdd` slash commands
-- TypeScript: 0 errors, clean build, 324KB bundle
+- Checkpoints, TDD engine, smart file discovery, reasoning memory
+- 42 tools total
 
 See [`CHANGELOG.md`](CHANGELOG.md) for the full history.