Merge pull request #6 from HumanAssisted/claude/review-repo-quality-29NH7

fix: update stale lock files to match declared dependency versions

Author: Hendler

Makefile

@@ -1,5 +1,5 @@
 .PHONY: test test-python test-node test-go test-rust \
-        versions check-versions \
+        versions check-versions check-jacs-versions \
         release-node release-python release-rust release-all \
         release-delete-tags help
 
@@ -14,6 +14,13 @@ PYTHON_VERSION := $(shell grep '^version' python/pyproject.toml | head -1 | sed
 NODE_VERSION := $(shell grep '"version"' node/package.json | head -1 | sed 's/.*: *"\(.*\)".*/\1/')
 PLUGIN_VERSION := $(shell grep '"version"' .claude-plugin/plugin.json | head -1 | sed 's/.*: *"\(.*\)".*/\1/')
 
+# JACS dependency versions across SDKs
+JACS_RUST := $(shell grep '^jacs ' rust/haiai/Cargo.toml | sed 's/.*"\(=*[0-9][^"]*\)".*/\1/' | sed 's/^=//')
+JACS_RUST_CLI := $(shell grep '^jacs ' rust/haiai-cli/Cargo.toml | sed 's/.*"\(=*[0-9][^"]*\)".*/\1/' | sed 's/^=//')
+JACS_RUST_MCP := $(shell grep '^jacs ' rust/hai-mcp/Cargo.toml | sed 's/.*"\(=*[0-9][^"]*\)".*/\1/' | sed 's/^=//')
+JACS_PYTHON := $(shell grep 'jacs==' python/pyproject.toml | sed 's/.*jacs==\([^"]*\)".*/\1/')
+JACS_NODE := $(shell grep '@hai.ai/jacs' node/package.json | head -1 | sed 's/.*: *"\(.*\)".*/\1/')
+
 # ============================================================================
 # TEST
 # ============================================================================
@@ -70,6 +77,23 @@ check-versions:
 		echo "ERROR: haiai ($(RUST_VERSION)) != plugin ($(PLUGIN_VERSION))"; exit 1; fi
 	@echo "All versions match: $(RUST_VERSION)"
 
+check-jacs-versions:
+	@echo "JACS dependency versions:"
+	@echo "  rust/haiai      $(JACS_RUST)"
+	@echo "  rust/haiai-cli  $(JACS_RUST_CLI)"
+	@echo "  rust/hai-mcp    $(JACS_RUST_MCP)"
+	@echo "  python          $(JACS_PYTHON)"
+	@echo "  node            $(JACS_NODE)"
+	@if [ "$(JACS_RUST)" != "$(JACS_RUST_CLI)" ]; then \
+		echo "ERROR: jacs in haiai ($(JACS_RUST)) != haiai-cli ($(JACS_RUST_CLI))"; exit 1; fi
+	@if [ "$(JACS_RUST)" != "$(JACS_RUST_MCP)" ]; then \
+		echo "ERROR: jacs in haiai ($(JACS_RUST)) != hai-mcp ($(JACS_RUST_MCP))"; exit 1; fi
+	@if [ "$(JACS_RUST)" != "$(JACS_PYTHON)" ]; then \
+		echo "ERROR: jacs in haiai ($(JACS_RUST)) != python ($(JACS_PYTHON))"; exit 1; fi
+	@if [ "$(JACS_RUST)" != "$(JACS_NODE)" ]; then \
+		echo "ERROR: jacs in haiai ($(JACS_RUST)) != node ($(JACS_NODE))"; exit 1; fi
+	@echo "All JACS versions match: $(JACS_RUST)"
+
 # ============================================================================
 # GITHUB CI RELEASE (via git tags)
 # ============================================================================
@@ -107,7 +131,7 @@ release-node:
 	git push origin node/v$(NODE_VERSION)
 	@echo "Tagged node/v$(NODE_VERSION) - CI will publish to npm"
 
-release-all: check-versions release-rust
+release-all: check-versions check-jacs-versions release-rust
 	@echo "Waiting 30s for Rust CI to start building CLI binaries..."
 	@sleep 30
 	$(MAKE) release-python release-node
@@ -129,7 +153,8 @@ help:
 	@echo ""
 	@echo "VERSION INFO:"
 	@echo "  make versions        Show all detected versions"
-	@echo "  make check-versions  Verify all package versions match"
+	@echo "  make check-versions       Verify all package versions match"
+	@echo "  make check-jacs-versions  Verify JACS dep versions match across SDKs"
 	@echo ""
 	@echo "TEST:"
 	@echo "  make test            Run all tests"

README.md

@@ -2,7 +2,7 @@
 
 Give your AI agent an email address. Register, get a `@hai.ai` address, and build a reputation.
 
-Official SDKs for the [HAI.AI](https://hai.ai) platform -- cryptographic agent identity, signed email, and conflict-resolution benchmarking for AI agents.
+Official SDKs for the [HAI.AI](https://hai.ai) platform -- build helpful, trustworthy AI agents with cryptographic identity, signed email, and verified benchmarks.
 
 ## Install
 
@@ -26,7 +26,7 @@ This gives you the `haiai` binary with built-in MCP server.
 
 ```toml
 [dependencies]
-haiai = "0.1.4"
+haiai = "0.1.5"
 ```
 
 ### Python

agents.md

@@ -0,0 +1,76 @@
+# Agents — Lessons Learned
+
+Quality audit of the HAIAI SDK (Python, Node, Go, Rust) — March 2026.
+
+## Critical Findings
+
+### Wrong endpoints (Go)
+- `ProRun()` called `/api/benchmark/subscribe` instead of `/api/benchmark/purchase`.
+- `GetAgentAttestation()` used singular `/attestation` instead of plural `/attestations`.
+- Key lookup functions (`FetchKeyByEmail`, etc.) defaulted to a separate `keys.hai.ai` host instead of the main HAI endpoint.
+- **Lesson:** Endpoint paths drift silently across SDKs. The `fixtures/contract_endpoints.json` fixture now exists to catch this — keep it updated when adding new endpoints.
+
+### Missing payload fields (Python, Go)
+- Python `hello_world()` omitted `agent_id` from the POST body (present in the other 3 SDKs).
+- `benchmark()` in Python and Go omitted `"transport": "sse"`.
+- **Lesson:** When one SDK adds a field, grep all SDKs for the same call and confirm parity.
+
+## High-Priority Patterns
+
+### No retry / no backoff
+- Go and Rust had zero retry logic. Node threw immediately on 429.
+- **Fix:** All SDKs now retry on `[429, 500, 502, 503, 504]` with exponential backoff (default 3 attempts). The status-code list is validated by a cross-SDK contract test (`test_retryable_status_codes_match_python`).
+- **Lesson:** Retry policy is a cross-cutting concern — treat it like a shared spec, not per-SDK discretion.
+
+### Unbounded reads (Go)
+- `io.ReadAll()` without a size cap could exhaust memory on malicious responses.
+- **Fix:** `limitedReadAll()` helper caps at 10 MB.
+- **Lesson:** Any `ReadAll`/`.text()`/`.read()` on an HTTP response should have a size limit.
+
+## Medium-Priority Patterns
+
+### Private key exposure (Node)
+- Private key was stored as an enumerable property, visible in `JSON.stringify()` and property iteration.
+- **Fix:** Moved to a module-level `WeakMap`, non-enumerable and non-serializable.
+- **Lesson:** Secrets should never be plain object properties. Use `WeakMap`, closures, or `Object.defineProperty` with `enumerable: false`.
+
+### Hardcoded passphrase (Node)
+- `register()` used `"register-temp"` as a temp key passphrase.
+- **Fix:** `crypto.randomBytes()`.
+- **Lesson:** Grep for string literals that look like passphrases/tokens — they're easy to miss in review.
+
+### Base URL validation
+- Python, Node, and Rust accepted arbitrary URL schemes (`ftp://`, `file://`, `javascript://`).
+- **Fix:** All SDKs now reject non-`http(s)://` schemes at construction time.
+- **Lesson:** Validate inputs at the boundary, not deep in the call chain.
+
+### Unbounded reconnection (Node, Rust)
+- SSE/WebSocket reconnection loops had no cap — could retry forever.
+- **Fix:** `maxReconnectAttempts` (default 10) with exponential backoff.
+- **Lesson:** Every retry loop needs a ceiling.
+
+### Missing SSE timeout (Go)
+- SSE HTTP client had no `ResponseHeaderTimeout` — could hang indefinitely.
+- **Fix:** 30-second timeout on response headers.
+
+### Race conditions (Go)
+- Mutable fields (`haiAgentID`, `agentEmail`) accessed without synchronization.
+- **Fix:** `sync.RWMutex` around mutable state.
+- **Lesson:** Any field written after construction needs a mutex in Go.
+
+### Missing query parameters (Python, Go, Node)
+- `list_messages()` and `search_messages()` were missing `has_attachments`, `since`, `until` filters that Rust already had.
+- **Lesson:** When Rust (the reference implementation) has a feature, all SDKs should too.
+
+### Reply endpoint undocumented (Rust)
+- Rust uses a server-side `/email/reply` endpoint; other SDKs compose client-side. Neither approach was documented.
+- **Fix:** Added to `fixtures/contract_endpoints.json` with a migration note.
+- **Lesson:** Architectural divergences between SDKs need explicit documentation, not just code.
+
+## Process Takeaways
+
+1. **Contract fixtures prevent drift.** `fixtures/contract_endpoints.json` is the source of truth for endpoints. Add new entries there first.
+2. **Cross-SDK grep is mandatory.** Before merging a behavior change in one SDK, grep the same function/field name across all four.
+3. **Test the sad path.** Most bugs were in error handling, retry logic, and edge cases — not the happy path.
+4. **Security is a default, not a feature.** Key exposure, hardcoded secrets, and unbounded reads were all "it works" code that was silently dangerous.
+5. **Rust is the reference.** When in doubt about what a function should do, check the Rust implementation first — it tends to be the most complete.

fixtures/contract_endpoints.json

@@ -14,5 +14,11 @@
     "method": "POST",
     "path": "/api/v1/agents/jobs/{job_id}/response",
     "auth_required": true
+  },
+  "reply": {
+    "method": "POST",
+    "path": "/api/agents/{agent_id}/email/reply",
+    "auth_required": true,
+    "note": "Server-side reply endpoint. Rust SDK uses this directly; Python/Node/Go currently fetch the original client-side and compose locally. Other SDKs should migrate to this endpoint for consistency."
   }
 }

go/README.md

@@ -1,6 +1,6 @@
 # haiai-go -- Go SDK
 
-Give your AI agent an email address. Go SDK for the [HAI.AI](https://hai.ai) platform -- cryptographic agent identity, signed email, and conflict-resolution benchmarking.
+Give your AI agent an email address. Go SDK for the [HAI.AI](https://hai.ai) platform -- build helpful, trustworthy AI agents with cryptographic identity, signed email, and verified benchmarks.
 
 ## Install