From 45d52a74d2a007fba6386473cc2f70cc25043b44 Mon Sep 17 00:00:00 2001 From: Chaim Date: Tue, 14 Apr 2026 14:18:57 +0000 Subject: [PATCH] =?UTF-8?q?Fix=20agent=20wakeup:=20/wake=20=E2=86=92=20/wa?= =?UTF-8?q?keup,=20remove=20broken=20DB=20fallback?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The agents used /api/agents/{id}/wake (404) with a fallback of INSERT INTO agent_wakeup_requests. The DB insert creates only the wakeup record without a heartbeat_run, so the Paperclip dispatcher never processes it — agents get stuck in queued forever. Fix: - All agents: /wake → /wakeup (correct Paperclip API endpoint) - Remove all DB INSERT fallbacks, replace with warning - Document the rule in CLAUDE.md: always API, never DB insert - Save to memory for future conversations Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/agents/HEARTBEAT.md | 16 +------- .claude/agents/legal-analyst.md | 16 ++------ .claude/agents/legal-exporter.md | 14 +------ .claude/agents/legal-proofreader.md | 58 +---------------------------- .claude/agents/legal-qa.md | 14 +------ .claude/agents/legal-researcher.md | 14 +------ .claude/agents/legal-writer.md | 14 +------ CLAUDE.md | 15 ++++++++ 8 files changed, 29 insertions(+), 132 deletions(-) diff --git a/.claude/agents/HEARTBEAT.md b/.claude/agents/HEARTBEAT.md index c413580..588fee8 100644 --- a/.claude/agents/HEARTBEAT.md +++ b/.claude/agents/HEARTBEAT.md @@ -106,22 +106,10 @@ curl -s -X PATCH -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ ```bash curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ - "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \ + "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \ -d '{"reason": "סוכן [שמך] סיים משימה [issue-id] בסטטוס [done/blocked]. נדרשת בדיקה והחלטה על הצעד הבא."}' ``` -אם ה-API הזה לא עובד, השתמש ב-DB ישירות: -```bash -PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c " -INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type) -VALUES ( - (SELECT company_id FROM agents WHERE id = '$PAPERCLIP_AGENT_ID'), - '752cebdd-6748-4a04-aacd-c7ab0294ef33', - 'agent_completion', - 'סוכן סיים משימה — נדרשת בדיקה והחלטה על הצעד הבא', - 'queued', - 'agent' -);" -``` +**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.** ## 5. התראת מייל — כשנדרשת תשובה אנושית diff --git a/.claude/agents/legal-analyst.md b/.claude/agents/legal-analyst.md index c8eb5e1..698161b 100644 --- a/.claude/agents/legal-analyst.md +++ b/.claude/agents/legal-analyst.md @@ -210,21 +210,11 @@ FROM documents d WHERE d.case_id = '{case_id}' AND d.doc_type IN ('appeal', 'res ```bash curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ - "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \ + "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \ -d '{"reason": "מנתח משפטי סיים משימה [issue-id] בסטטוס [done/blocked]"}' ``` אם ה-API לא עובד: -```bash -PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c " -INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type) -VALUES ( - (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'), - '752cebdd-6748-4a04-aacd-c7ab0294ef33', - 'agent_completion', - 'מנתח משפטי סיים משימה — נדרשת בדיקה', - 'queued', 'agent' -);" -``` +**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.** **אם בדיקות שלב 6 נכשלו** — סטטוס issue = "blocked", פרסם comment עם פירוט מה נכשל, שלח מייל לחיים. @@ -379,7 +369,7 @@ X שאלות עומדות להכרעה: ```bash curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ - "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \ + "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \ -d '{"reason": "מנתח משפטי סיים העמקת ניתוח (pass 2) [issue-id] בסטטוס [done/blocked]"}' ``` אם ה-API לא עובד: diff --git a/.claude/agents/legal-exporter.md b/.claude/agents/legal-exporter.md index 386aac5..0c76093 100644 --- a/.claude/agents/legal-exporter.md +++ b/.claude/agents/legal-exporter.md @@ -78,21 +78,11 @@ tools: ```bash curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ - "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \ + "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \ -d '{"reason": "מייצא טיוטה סיים משימה [issue-id] בסטטוס [done/blocked]"}' ``` אם ה-API לא עובד: -```bash -PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c " -INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type) -VALUES ( - (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'), - '752cebdd-6748-4a04-aacd-c7ab0294ef33', - 'agent_completion', - 'מייצא טיוטה סיים משימה — נדרשת בדיקה', - 'queued', 'agent' -);" -``` +**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.** ## כללים קריטיים diff --git a/.claude/agents/legal-proofreader.md b/.claude/agents/legal-proofreader.md index 9276cf0..70d8e6c 100644 --- a/.claude/agents/legal-proofreader.md +++ b/.claude/agents/legal-proofreader.md @@ -62,60 +62,4 @@ tools: 1. **גיבוי**: העתק את הקובץ המקורי מ-`extracted/` לתיקיית `documents/backup/` עם סיומת `.pre-proofread.txt` 2. **כתוב** את הגרסה המתוקנת לתיקיית `documents/proofread/` (עם אותו שם קובץ כמו ב-`extracted/`) 3. עדכן את מסד הנתונים — שנה `extraction_status` ל-`proofread`: -```bash -PGPASSWORD="${PGPASSWORD:-$(grep DB_PASSWORD /home/chaim/.env | cut -d= -f2)}" \ -psql -h localhost -p 5432 -U "${DB_USER:-legal_ai}" -d "${DB_NAME:-legal_ai}" \ --c "UPDATE documents SET extraction_status = 'proofread', extracted_text = pg_read_file('/path/to/file.txt') WHERE id = '{doc_id}';" -``` -אם עדכון DB לא אפשרי, עדכן רק את הקובץ ודווח. - -### שלב 5: עדכון סטטוס ודיווח - -1. **עדכן סטטוס**: `case_update(case_number, status='proofread')` - -2. פרסם comment ב-Paperclip עם: -``` -## דוח הגהת מסמכים — תיק {case_number} - -### סיכום -- **מסמכים שנבדקו:** {count} -- **מסמכים שתוקנו:** {fixed_count} -- **סה"כ תיקונים:** {total_fixes} - -### פירוט לכל מסמך -| מסמך | ראשי תיבות | שגיאות OCR | הערות | -|------|------------|-----------|-------| -| {title} | {abbr_count} | {ocr_count} | {notes} | - -### מקומות לא ברורים -- {document}: סעיף {n} — [?] "{problematic_text}" -``` - -## כללים קריטיים - -1. **אל תשנה תוכן משפטי** — רק תיקוני OCR. אם מילה נראית מוזרה אבל היא מונח משפטי — אל תגע -2. **אל תדרוס בלי גיבוי** — תמיד העתק ל-`backup/` לפני שינוי -3. **ראשי תיבות ארוכים קודם** — `נתבייע` (5 תווים) לפני `עייד` (3 תווים) -4. **דווח מקומות מסופקים** — סמן `[?]` ותן לאדם להחליט -5. **אל תמציא טקסט** — אם חסר משהו, סמן `[...]` ואל תנחש -6. **קרא את כל המסמך** — לפעמים הקשר ממסמך שלם עוזר להבין מילה שבורה - -### העֵר את העוזר המשפטי (CEO) — חובה! -```bash -curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ - -H "Content-Type: application/json" \ - "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \ - -d '{"reason": "מגיה מסמכים סיים משימה [issue-id] בסטטוס [done/blocked]"}' -``` -אם ה-API לא עובד: -```bash -PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c " -INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type) -VALUES ( - (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'), - '752cebdd-6748-4a04-aacd-c7ab0294ef33', - 'agent_completion', - 'מגיה מסמכים סיים משימה — נדרשת בדיקה', - 'queued', 'agent' -);" -``` +**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.** diff --git a/.claude/agents/legal-qa.md b/.claude/agents/legal-qa.md index 7f96336..5f63596 100644 --- a/.claude/agents/legal-qa.md +++ b/.claude/agents/legal-qa.md @@ -109,18 +109,8 @@ tools: ```bash curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ - "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \ + "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \ -d '{"reason": "בודק איכות סיים משימה [issue-id] בסטטוס [done/blocked]"}' ``` אם ה-API לא עובד: -```bash -PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c " -INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type) -VALUES ( - (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'), - '752cebdd-6748-4a04-aacd-c7ab0294ef33', - 'agent_completion', - 'בודק איכות סיים משימה — נדרשת בדיקה', - 'queued', 'agent' -);" -``` +**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.** diff --git a/.claude/agents/legal-researcher.md b/.claude/agents/legal-researcher.md index 4c91199..a417beb 100644 --- a/.claude/agents/legal-researcher.md +++ b/.claude/agents/legal-researcher.md @@ -98,21 +98,11 @@ python3 /home/chaim/legal-ai/scripts/notify.py \ ```bash curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ - "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \ + "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \ -d '{"reason": "חוקר תקדימים סיים משימה [issue-id] בסטטוס [done/blocked]"}' ``` אם ה-API לא עובד: -```bash -PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c " -INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type) -VALUES ( - (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'), - '752cebdd-6748-4a04-aacd-c7ab0294ef33', - 'agent_completion', - 'חוקר תקדימים סיים משימה — נדרשת בדיקה', - 'queued', 'agent' -);" -``` +**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.** ## כללים - **דיוק** — ציין מספרי סעיפים, תאריכים, שמות שופטים diff --git a/.claude/agents/legal-writer.md b/.claude/agents/legal-writer.md index 1f9e3d0..c372347 100644 --- a/.claude/agents/legal-writer.md +++ b/.claude/agents/legal-writer.md @@ -160,21 +160,11 @@ case_update(case_number, status="drafted") ```bash curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ -H "Content-Type: application/json" \ - "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wake" \ + "$PAPERCLIP_API_URL/api/agents/752cebdd-6748-4a04-aacd-c7ab0294ef33/wakeup" \ -d '{"reason": "כותב החלטה סיים משימה [issue-id] בסטטוס [done/blocked]"}' ``` אם ה-API לא עובד: -```bash -PGPASSWORD="paperclip" psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c " -INSERT INTO agent_wakeup_requests (company_id, agent_id, source, reason, status, requested_by_actor_type) -VALUES ( - (SELECT company_id FROM agents WHERE id = '\$PAPERCLIP_AGENT_ID'), - '752cebdd-6748-4a04-aacd-c7ab0294ef33', - 'agent_completion', - 'כותב החלטה סיים משימה — נדרשת בדיקה', - 'queued', 'agent' -);" -``` +**⚠️ אסור להשתמש ב-INSERT INTO agent_wakeup_requests ישירות!** הכנסה ישירה ל-DB יוצרת רק את הבקשה בלי heartbeat_run — והסוכן לא יתעורר לעולם. **תמיד להשתמש ב-API בלבד.** **אם לא תעדכן סטטוס ל-drafted — בודק האיכות לא יוכל לרוץ!** diff --git a/CLAUDE.md b/CLAUDE.md index 031deca..45a80ce 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -103,6 +103,21 @@ --- +## Paperclip — כללי אינטגרציה קריטיים + +### Wakeup API — תמיד דרך API, לעולם לא דרך DB +- **הנתיב הנכון**: `POST /api/agents/{agent-id}/wakeup` עם `{"source": "...", "reason": "..."}` +- **⚠️ אסור**: `INSERT INTO agent_wakeup_requests` ישירות — זה יוצר רק את הרשומה בטבלה בלי `heartbeat_run`, והסוכן **לא יתעורר לעולם** +- **הסיבה**: ה-dispatcher של Paperclip מעבד `heartbeat_runs`, לא `agent_wakeup_requests`. רק ה-API יוצר את שניהם אטומית +- **Board API Key**: שמור ב-DB (`board_api_keys`), מאפשר גישה ל-API מ-CLI + +### ניתוב comments דרך CEO +- כשמשתמש כותב תגובה על issue ב-Paperclip, הפלאגין (`plugin-legal-ai`) מעיר את ה-CEO דרך `ctx.agents.invoke()` +- ה-CEO קורא את ה-comment, מחליט על ניתוב, ויוצר issue לסוכן המתאים +- כל הסוכנים חייבים לקרוא comments אחרונים לפני שהם מתחילים לעבוד (HEARTBEAT שלבים 2b-2c) + +--- + ## עקרונות כתיבה קריטיים 1. **"מבחן השופט"** — כל החלטה חייבת להיות קריאה לשופט שלא מכיר את התיק