azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: coord API — no-auth, DB softfail 503, agent tracking protocol

Browse Source 
- coord routers: removed JWT auth requirement (internal-only endpoints)
- error_handler: SQLAlchemy OperationalError/DisconnectionError → 503
  with Retry-After: 30 header instead of 500
- /health: live DB probe (SELECT 1) instead of static response
- CLAUDE.md: "Live State Tracking" section with full agent protocol
  for all projects — session start, lock claim/release, component
  state updates, softfail + local queue catch-up
- COORDINATION_PROTOCOL.md: softfail/catch-up section + server-side
  503 behavior documented

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-05-12 08:45:33 -07:00
parent 4879dda30e
commit a36ed8ec08
10 changed files with 70 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.claude/CLAUDE.md
View File

@@ -252,19 +252,7 @@ Full protocol reference: `.claude/COORDINATION_PROTOCOL.md`
### Cross-Session Messages (MANDATORY)
At session start and after every `/sync`, check for unread messages:
```
GET http://172.16.3.30:8001/api/coord/messages?to_session=<this-session>&unread_only=true
```
If unread messages exist, display each one prominently before any other work:
```
============================================================
MESSAGE FROM <from_session> — <subject>
============================================================
<body>
============================================================
```
Mark as read via `PUT /api/coord/messages/{id}/read` after displaying.
See the **Session Start Protocol** in "Live State Tracking" above. Messages must be displayed and marked read before any other work.
Also scan session logs pulled during `/sync` for legacy `## Note for <user>` sections (transitional — older sessions still use markdown).

43
.claude/COORDINATION_PROTOCOL.md
View File

@@ -2,7 +2,7 @@
Cross-session coordination uses the ClaudeTools API at `http://172.16.3.30:8001/api/coord/`. This replaces PROJECT_STATE.md files.
All endpoints require a `session_id` string identifying the current session (e.g., `DESKTOP-0O8A1RL/claude-main`). No auth token required for coordination endpoints.
No auth token required for coordination endpoints — they are internal-only on the 172.16.3.30 private network. Pass `session_id` in the request body or as a query parameter to identify the calling session (e.g., `DESKTOP-0O8A1RL/claude-main`).
---
@@ -187,6 +187,47 @@ Free-form — add new slugs as needed. Does NOT foreign-key to the projects tabl
---
## Softfail and Catch-Up
The coordination API must never block work. If it is unavailable:
**On any network error, timeout, or 5xx response:**
1. Log the failed call to `.claude/coord-queue.jsonl` (one JSON object per line):
```json
{"ts":"2026-05-12T15:30:00Z","method":"PUT","path":"/api/coord/components/gururmm/server","body":{"state":"deployed","version":"0.3.0","notes":"...","updated_by":"DESKTOP-0O8A1RL/claude-main"}}
```
2. Continue working. Do not retry immediately.
**On 503 with `Retry-After` header:**
Wait the specified seconds, then retry once. If the retry also fails, queue it.
**Catch-up (session start and after `/sync`):**
```bash
# If coord-queue.jsonl exists and is non-empty:
while read -r line; do
method=$(echo "$line" | jq -r .method)
path=$(echo "$line" | jq -r .path)
body=$(echo "$line" | jq -r .body)
curl -s -X "$method" "http://172.16.3.30:8001$path" -H "Content-Type: application/json" -d "$body"
done < .claude/coord-queue.jsonl
# Remove the file only if all calls succeeded
```
The queue file lives in `.claude/coord-queue.jsonl` (gitignored — local to each workstation).
---
## API Softfail Behavior (Server Side)
When the MariaDB database is unavailable:
- Coord endpoints return `503 Service Unavailable` with header `Retry-After: 30`
- Response body: `{"detail": "Database unavailable. Retry after 30 seconds.", "retry_after": 30}`
- `GET /health` reflects DB status: `{"status":"degraded","database":"disconnected"}`
This behavior is implemented in the API server and does not need to be coded by agents.
---
## Migration Note
`projects/*/PROJECT_STATE.md` files are ARCHIVED — read-only historical reference. Do not edit them. Use this API for all live coordination going forward.