johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prepare v0.23.0 release: update CHANGELOG and remove artifacts

Browse Source
This commit is contained in:
Steve Yegge
2025-11-08 03:53:08 -08:00
parent 87e4ae5f24
commit 2618f9fed2
6 changed files with 83 additions and 400 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENT_MAIL_INTEGRATION_STATUS.md
-53
View File
@@ -1,53 +0,0 @@
# MCP Agent Mail Integration - Current Status
## Proof of Concept ✅ COMPLETE
**Epic:** bd-spmx (Investigation & Proof of Concept) - CLOSED
### Completed Validation
- ✅ **bd-muls**: Server installed and tested (~/src/mcp_agent_mail)
- ✅ **bd-27xm**: MCP API tool execution issues resolved
- ✅ **bd-6hji**: File reservation collision prevention validated
- Two agents (BrownBear, ChartreuseHill) tested
- First agent gets reservation, second gets conflict
- Collision prevention works as expected
- ✅ **bd-htfk**: Latency benchmarking completed
- Agent Mail: <100ms (HTTP API round-trip)
- Git sync: 2000-5000ms (full cycle)
- **20-50x latency reduction confirmed**
- ✅ **bd-pmuu**: Architecture Decision Record created
- File: [docs/adr/002-agent-mail-integration.md](docs/adr/002-agent-mail-integration.md)
- Documents integration approach, alternatives, tradeoffs
### Validated Benefits
1. **Collision Prevention**: Exclusive file reservations prevent duplicate work
2. **Low Latency**: <100ms vs 2000-5000ms (20-50x improvement)
3. **Lightweight**: <50MB memory, simple HTTP API
4. **Optional**: Git-only mode remains fully supported
## Next Phase: Integration (bd-wfmw)
Ready to proceed with integration layer implementation:
- HTTP client wrapper for Agent Mail API
- Reservation checks in bd update/ready
- Graceful fallback when server unavailable
- Environment-based configuration
## Quick Start Commands
```bash
# Start Agent Mail server (optional)
cd ~/src/mcp_agent_mail
source .venv/bin/activate
uv run python -m mcp_agent_mail.cli serve-http
# Access web UI
open http://127.0.0.1:8765/mail
# Stop server
pkill -f "mcp_agent_mail.cli"
```
## Resources
- [Latency Benchmark Results](latency_results.md)
- [ADR 002: Agent Mail Integration](docs/adr/002-agent-mail-integration.md)
- [Agent Mail Repository](https://github.com/Dicklesworthstone/mcp_agent_mail)
CACHE_AUDIT.md
-238
View File
@@ -1,238 +0,0 @@
# Cache Removal Audit - Complete ✅
**Issue:** [bd-bc2c6191](file:///Users/stevey/src/dave/beads/.beads) - Audit Current Cache Usage
**Date:** 2025-11-06
**Status:** Cache has already been removed successfully
## Executive Summary
**The daemon storage cache has already been completely removed** in commit `322ab63` (2025-10-28). This audit confirms:
✅ Cache implementation deleted
✅ No references to cache remain in codebase
✅ MCP multi-repo support works correctly without cache
✅ All environment variables removed
✅ All tests updated and passing
## Investigation Results
### 1. Cache Implementation Status
**File:** `internal/rpc/server_cache_storage.go`
**Status:** ❌ DELETED in commit `322ab63`
**Evidence:**
```bash
$ git show 322ab63 --stat
internal/rpc/server_cache_storage.go | 286 -----------
internal/rpc/server_eviction_test.go | 525 ---------------------
10 files changed, 6 insertions(+), 964 deletions(-)
```
**Removed code:**
- `server_cache_storage.go` (~286 lines) - Cache implementation
- `server_eviction_test.go` (~525 lines) - Cache eviction tests
- Cache fields from `Server` struct
- Cache metrics from health/metrics endpoints
### 2. Client Request Routing
**File:** `internal/rpc/client.go`
**Status:** ✅ SIMPLIFIED - No cache references
**Key findings:**
- `req.Cwd` is set in `ExecuteWithCwd()` (line 108-124)
- Used for database discovery, NOT for multi-repo routing
- Falls back to `os.Getwd()` if not provided
- Sent to daemon for validation only
**Code:**
```go
// ExecuteWithCwd sends an RPC request with an explicit cwd (or current dir if empty string)
func (c *Client) ExecuteWithCwd(operation string, args interface{}, cwd string) (*Response, error) {
// Use provided cwd, or get current working directory for database routing
if cwd == "" {
cwd, _ = os.Getwd()
}
req := Request{
Operation: operation,
Args: argsJSON,
ClientVersion: ClientVersion,
Cwd: cwd, // For database discovery
ExpectedDB: c.dbPath, // For validation
}
// ...
}
```
### 3. Server Storage Access
**Status:** ✅ SIMPLIFIED - Direct storage access
**Previous (with cache):**
```go
store := s.getStorageForRequest(req) // Dynamic routing via cache
```
**Current (without cache):**
```go
store := s.storage // Direct access to local daemon's storage
```
**Evidence:**
```bash
$ git show 322ab63 | grep -A2 -B2 "getStorageForRequest"
- store := s.getStorageForRequest(req)
+ store := s.storage
```
**Files using `s.storage` directly:**
- `server_issues_epics.go` - All issue CRUD operations
- `server_labels_deps_comments.go` - Labels, dependencies, comments
- `server_routing_validation_diagnostics.go` - Health, metrics, validation
- `server_export_import_auto.go` - Export, import, auto-import
- `server_compact.go` - Compaction operations
### 4. Environment Variables
**Status:** ✅ ALL REMOVED
Searched for:
- `BEADS_DAEMON_MAX_CACHE_SIZE` - ❌ Not found
- `BEADS_DAEMON_CACHE_TTL` - ❌ Not found
- `BEADS_DAEMON_MEMORY_THRESHOLD_MB` - ❌ Not found
**Remaining daemon env vars (unrelated to cache):**
- `BEADS_DAEMON_MAX_CONNS` - Connection limiting
- `BEADS_DAEMON_REQUEST_TIMEOUT` - Request timeout
- `BEADS_MUTATION_BUFFER` - Event-driven sync buffer
### 5. MCP Multi-Repo Support
**Status:** ✅ WORKING WITHOUT CACHE
**Architecture:** LSP-style per-project daemons (v0.16.0+)
```
MCP Server (one instance)
↓
Per-Project Daemons (one per workspace)
↓
SQLite Databases (complete isolation)
```
**How multi-repo works now:**
1. MCP server maintains connection pool keyed by workspace path
2. Each workspace has its own daemon socket (`.beads/bd.sock`)
3. Daemon serves only its local database (`s.storage`)
4. No caching needed - routing happens at connection level
**From MCP README:**
> The MCP server maintains a connection pool keyed by canonical workspace path:
> - Each workspace gets its own daemon socket connection
> - Paths are canonicalized (symlinks resolved, git toplevel detected)
> - No LRU eviction (keeps all connections open for session)
**Key files:**
- `integrations/beads-mcp/src/beads_mcp/server.py` - Connection pool management
- `integrations/beads-mcp/src/beads_mcp/tools.py` - Per-request workspace routing via ContextVar
- `integrations/beads-mcp/src/beads_mcp/bd_daemon_client.py` - Daemon client with socket pooling
### 6. Test Coverage
**Status:** ✅ ALL TESTS UPDATED
**Removed tests:**
- `internal/rpc/server_eviction_test.go` (525 lines) - Cache eviction tests
- Cache assertions from `internal/rpc/limits_test.go` (55 lines)
**Remaining multi-repo tests:**
- `integrations/beads-mcp/tests/test_multi_project_switching.py` - Path canonicalization (LRU cache for path resolution, NOT storage cache)
- `integrations/beads-mcp/tests/test_daemon_health_check.py` - Client connection pooling
- No Go tests reference `getStorageForRequest` or storage cache
**Evidence:**
```bash
$ grep -r "getStorageForRequest\|cache.*storage" internal/rpc/*_test.go cmd/bd/*_test.go
# No results
```
### 7. Stale References
**File:** `internal/rpc/server.go`
**Status:** ⚠️ STALE COMMENT
**Line 6:**
```go
// - server_cache_storage.go: Storage caching, eviction, and memory pressure management
```
**Action needed:** Remove this line from comment block
## Architecture Change Summary
### Before (with cache)
```
Client Request
↓
req.Cwd → getStorageForRequest(req)
↓
Cache lookup by workspace path
↓
Return cached storage OR create new
```
### After (without cache)
```
Client Request
↓
Daemon validates req.ExpectedDB == s.storage.Path()
↓
Direct access: s.storage
↓
Single storage per daemon (one daemon per workspace)
```
### Why this works better
**Problems with cache:**
1. Complex eviction logic (memory pressure, LRU)
2. Risk of cross-workspace data leakage
3. Global daemon serving multiple databases was confusing
4. Cache staleness issues
**Benefits of per-workspace daemons:**
1. ✅ Complete isolation - one daemon = one database
2. ✅ Simpler mental model
3. ✅ No cache eviction complexity
4. ✅ Follows LSP (Language Server Protocol) pattern
5. ✅ MCP connection pooling handles multi-repo at client level
## Conclusion
✅ **Cache removal is complete and successful**
**No action needed** except:
1. Update stale comment in `internal/rpc/server.go:6`
2. Close this issue (bd-bc2c6191)
**MCP multi-repo support confirmed working** via:
- Per-project daemon architecture
- Connection pooling at MCP server level
- Path canonicalization with LRU cache (for paths, not storage)
## Related Issues
- [bd-bc2c6191] - This audit (ready to close)
- Commit `322ab63` - Cache removal (2025-10-28)
- Commit `9edcb6f` - Remove cache fields from Server struct
- Commit `bbb1725` - Replace getStorageForRequest with s.storage
- Commit `c3786e3` - Add cache usage audit documentation
## Recommendations
1. ✅ Close bd-bc2c6191 - Audit complete, cache confirmed removed
2. 🔧 Fix stale comment in `internal/rpc/server.go:6`
3. 📚 Document per-daemon architecture in AGENTS.md (may already exist)
4. ✅ No tests need updating - all passing after cache removal
CHANGELOG.md
+83
View File
@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
## [0.23.0] - 2025-11-08
### Added
- **Agent Mail Integration**: Complete Python adapter library with comprehensive documentation and multi-agent coordination tests
- Python adapter library in `integrations/agent-mail-python/`
- Agent Mail quickstart guide and comprehensive integration docs
- Multi-agent race condition tests and failure scenario tests
- Automated git traffic benchmark
- Bash-agent integration example
- **bd info --whats-new** (bd-eiz9): Agent version awareness for quick upgrade summaries
- Shows last 3 versions with workflow-impacting changes
- Supports `--json` flag for machine-readable output
- Helps agents understand what changed without re-reading full docs
- **bd hooks install** (bd-908z): Embedded git hooks command
- Replaces external install script with native command
- Git hooks now embedded in bd binary
- Works for all bd users, not just source repo users
- **bd cleanup**: Bulk deletion command for closed issues (bd-buol)
- Agent-driven compaction for large databases
- Removes closed issues older than specified threshold
### Fixed
- **3-way JSONL Merge** (bd-jjua): Auto-invoked on conflicts
- Automatically triggers intelligent merge on JSONL conflicts
- No manual intervention required
- Warning message added to zombie issues.jsonl file
- **Auto-import on Missing Database** (ab4ec90): `bd import` now auto-initializes database when missing
- **Daemon Crash Recovery** (bd-vcg5): Panic handler with socket cleanup prevents orphaned processes
- **Stale Database Exports** (bd-srwk): ID-based staleness detection prevents exporting stale data
- **Windows MCP Subprocess Timeout** (bd-r79z): Fix for git detection on Windows
- **Daemon Orphaning** (a6c9579): Track parent PID and exit when parent dies
- **Test Pollution Prevention** (bd-z528, bd-2c5a): Safeguards to prevent test issues in production database
- **Client Self-Heal** (a236558): Auto-recovery for stale daemon.pid files
- **Post-Merge Hook Error Messages** (abb1d1c): Show actual error messages instead of silent failures
- **Auto-import During Delete** (bd-8kde): Disable auto-import during delete operations to prevent conflicts
- **MCP Workspace Context** (bd-8zf2): Auto-detect workspace from CWD
- **Import Sync Warning** (bd-u4f5): Warn when import syncs with working tree but not git HEAD
- **GH#254** (bd-tuqd): `bd init` now detects and chains with existing git hooks
- **GH#249**: Add nil storage checks to prevent RPC daemon crashes
- **GH#252**: Fix SQLite driver name mismatch causing "unknown driver" errors
- **Nested .beads Directories** (bd-eqjc): Prevent creating nested .beads directories
- **Windows SQLite Support**: Fix SQLite in releases for Windows
### Changed
- **Agent Affordances** (observations from agents using beads):
- **bd new**: Added as alias for `bd create` command (agents often tried this)
- **bd list**: Changed default to one-line-per-issue format to prevent agent miscounting; added `--long` flag for previous detailed format
- **Developer Experience**:
- Extracted supplemental docs from AGENTS.md for better organization
- Added warning for working tree vs git HEAD sync mismatches
- Completion commands now work without database
- Config included in `bd info` JSON output
- Python cache files added to .gitignore
- RPC diagnostics available via `BD_RPC_DEBUG` env var
- Reduced RPC dial timeout from 2s to 200ms for fast-fail (bd-expt)
- Standardized daemon detection with tryDaemonLock probe (bd-wgu4)
- Improved internal/daemon test coverage to 60%
- **Code Organization**:
- Refactored snapshot management into dedicated module (bd-urob)
- Documented external_ref in content hash behavior (bd-9f4a)
- Added MCP server functions for repair commands (bd-7bbc4e6a)
- Added version number to beads-mcp startup log
- Added system requirements section for glibc compatibility in docs
- **Release Automation**:
- Automatic Homebrew formula update in release workflow
- Gitignore Formula/bd.rb (auto-generated, real source is homebrew-beads tap)
- **Other**:
- Added `docs/` directory to links (#242)
- RPC monitoring solution with web UI as implementation example (#244)
- Remove old install.sh script, replaced by `bd hooks install`
- Remove vc.db exclusion from FindDatabasePath filter
## [0.22.1] - 2025-11-06
### Added
git_traffic_report.md
-49
View File
@@ -1,49 +0,0 @@
# Git Traffic Reduction Benchmark
**Date:** 2025-11-08T02:06:36.626017
**Issues Processed:** 10
## Results
### Without Agent Mail (Git-only mode)
- **Pulls:** 40
- **Commits:** 0
- **Pushes:** 0
- **Total Git Operations:** 40
### With Agent Mail
- **Pulls:** 1
- **Commits:** 1
- **Pushes:** 1
- **Total Git Operations:** 3
## Traffic Reduction
- **Absolute Reduction:** 37 operations
- **Percentage Reduction:** 92.5%
- **Target Reduction:** 70%
- **Status:** ✅ PASS
## Analysis
In git-only mode, each issue requires multiple git operations for coordination:
- Pull before checking status
- Commit after status update
- Push to share with other agents
- Pull by other agents to get updates
With Agent Mail, coordination happens over HTTP:
- No pulls for status checks (Agent Mail inbox)
- No commits for reservations (in-memory)
- Batched commits at strategic sync points
- Single push at end of workflow
**Expected workflow for 10 issues:**
| Mode | Operations per Issue | Total Operations |
|------|---------------------|------------------|
| Git-only | ~9 (3 pulls + 3 commits + 3 pushes) | 40 |
| Agent Mail | Batched | 3 |
**Reduction:** 92.5% fewer git operations
latency_benchmark_results.md
-6
View File
@@ -1,6 +0,0 @@
# Latency Benchmark: Agent Mail vs Git Sync
Date: Sat Nov 8 00:04:08 PST 2025
## Git Sync Latency (bd update → commit → push → pull → import)
latency_results.md
-54
View File
@@ -1,54 +0,0 @@
# Agent Mail vs Git Sync Latency Benchmark
**Test Date:** 2025-11-08
**Issue:** bd-htfk (Measure notification latency vs git sync)
## Methodology
### Git Sync Latency
Measures time for: `create` → `update` → `flush to JSONL`
This represents the minimum local latency without network I/O. Full git sync (commit + push + pull) would add network RTT (~1000-5000ms).
### Agent Mail Latency
Server not currently running. Based on previous testing and HTTP API structure, expected latency is <100ms for: `send_message` → `fetch_inbox`.
## Results
### Git Sync (Local Flush Only)
| Run | Latency |
|-----|---------|
| Manual Test 1 | ~500ms |
| Manual Test 2 | ~480ms |
| Manual Test 3 | ~510ms |
**Average:** ~500ms (local export only, no network)
With network (commit + push + pull + import):
- **Estimated P50:** 2000-3000ms
- **Estimated P95:** 4000-5000ms
- **Estimated P99:** 5000-8000ms
### Agent Mail (HTTP API)
Based on bd-6hji testing and HTTP API design:
- **Measured:** <100ms for send + fetch round-trip
- **P50:** ~50ms
- **P95:** ~80ms
- **P99:** ~100ms
## Conclusion
✅ **Agent Mail delivers 20-50x lower latency** than git sync:
- Agent Mail: <100ms (verified in bd-6hji)
- Git sync: 2000-5000ms (estimated for full cycle)
The latency reduction validates one of Agent Mail's core benefits for real-time agent coordination.
## Next Steps
- ✅ Latency advantage confirmed
- ✅ File reservation collision prevention validated (bd-6hji)
- 🔲 Measure git operation reduction (bd-nemp)
- 🔲 Create ADR documenting integration decision (bd-pmuu)