universal-agent-protocol 0.5.0

package/templates/hooks/pre-compact.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# UAP Pre-Compact Hook for Claude Code
+# 1. Checks compliance state and warns on violations
+# 2. Writes a timestamp marker to the daily log before context compaction
+# 3. Marks any agents registered by this session as completed
+# Fails safely - never blocks the agent.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
+COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"
+
+if [ ! -f "$DB_PATH" ]; then
+  exit 0
+fi
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Record a compaction marker in memory so sessions can detect context resets
+sqlite3 "$DB_PATH" "
+  INSERT OR IGNORE INTO memories (timestamp, type, content)
+  VALUES ('$TIMESTAMP', 'action', '[pre-compact] Context compaction at $TIMESTAMP');
+" 2>/dev/null || true
+
+# Check if any lessons were stored this session
+recent_lessons=$(sqlite3 "$DB_PATH" "
+  SELECT COUNT(*) FROM session_memories
+  WHERE timestamp >= datetime('now', '-2 hours')
+    AND type = 'decision';
+" 2>/dev/null || echo "0")
+
+output=""
+
+# Compliance reminder on compaction
+output+="<system-reminder>"$'\n'
+output+="## UAP COMPLIANCE REMINDER (Pre-Compact)"$'\n'
+output+=""$'\n'
+output+="Context is being compacted. Before continuing work after compaction:"$'\n'
+output+="1. Re-run: uap task ready"$'\n'
+output+="2. Re-query memory for current task context"$'\n'
+output+="3. Check for stale worktrees: uap worktree list"$'\n'
+output+=""$'\n'
+
+if [ "$recent_lessons" = "0" ]; then
+  output+="WARNING: No lessons stored this session. Before compaction completes,"$'\n'
+  output+="store a summary: sqlite3 ./agents/data/memory/short_term.db \"INSERT INTO session_memories (session_id,timestamp,type,content,importance) VALUES ('current',datetime('now'),'decision','<summary>',7);\""$'\n'
+fi
+
+output+="</system-reminder>"$'\n'
+
+echo "$output"
+
+# Clean up agents with recent heartbeats (likely from this session being compacted)
+if [ -f "$COORD_DB" ]; then
+  sqlite3 "$COORD_DB" "
+    DELETE FROM work_claims WHERE agent_id IN (
+      SELECT id FROM agent_registry
+      WHERE status='active' AND last_heartbeat >= datetime('now','-5 minutes')
+    );
+    UPDATE work_announcements SET completed_at='$TIMESTAMP'
+      WHERE completed_at IS NULL AND agent_id IN (
+        SELECT id FROM agent_registry
+        WHERE status='active' AND last_heartbeat >= datetime('now','-5 minutes')
+      );
+    UPDATE agent_registry SET status='completed'
+      WHERE status='active' AND last_heartbeat >= datetime('now','-5 minutes');
+  " 2>/dev/null || true
+fi

package/templates/hooks/session-start.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# UAP Session Start Hook for Claude Code
+# COMPLIANCE ENFORCEMENT: Outputs mandatory protocol checklist
+# that the AI agent MUST complete before any work begins.
+# Fails safely - never blocks the agent.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DB_PATH="${PROJECT_DIR}/agents/data/memory/short_term.db"
+COORD_DB="${PROJECT_DIR}/agents/data/coordination/coordination.db"
+
+if [ ! -f "$DB_PATH" ]; then
+  exit 0
+fi
+
+# Clean stale agents from coordination DB (heartbeat >24h old)
+if [ -f "$COORD_DB" ]; then
+  sqlite3 "$COORD_DB" "
+    DELETE FROM work_claims WHERE agent_id IN (
+      SELECT id FROM agent_registry
+      WHERE status IN ('active','idle') AND last_heartbeat < datetime('now','-24 hours')
+    );
+    DELETE FROM work_announcements WHERE agent_id IN (
+      SELECT id FROM agent_registry
+      WHERE status IN ('active','idle') AND last_heartbeat < datetime('now','-24 hours')
+    ) AND completed_at IS NULL;
+    UPDATE agent_registry SET status='failed'
+      WHERE status IN ('active','idle') AND last_heartbeat < datetime('now','-24 hours');
+    DELETE FROM agent_registry
+      WHERE status IN ('completed','failed') AND started_at < datetime('now','-7 days');
+    DELETE FROM agent_messages WHERE created_at < datetime('now','-24 hours');
+  " 2>/dev/null || true
+fi
+
+output=""
+
+# ============================================================
+# COMPLIANCE ENFORCEMENT BLOCK
+# This is injected as system context. The AI MUST follow these.
+# ============================================================
+output+="<system-reminder>"$'\n'
+output+="## UAP COMPLIANCE - MANDATORY PROTOCOL"$'\n'
+output+=""$'\n'
+output+="You MUST complete these steps IN ORDER before doing ANY work."$'\n'
+output+="Skipping ANY step is a critical protocol violation."$'\n'
+output+=""$'\n'
+output+="### BEFORE WORK (execute these commands NOW):"$'\n'
+output+="1. Run: uap task ready"$'\n'
+output+="2. Run: sqlite3 ./agents/data/memory/short_term.db \"SELECT type, substr(content,1,80) FROM memories ORDER BY id DESC LIMIT 5;\""$'\n'
+output+="3. Run: uap memory query \"<relevant to user request>\""$'\n'
+output+="4. On work request: Run: uap task create --type <task|bug|feature> --title \"<description>\""$'\n'
+output+=""$'\n'
+output+="### DURING WORK:"$'\n'
+output+="5. ALL file changes MUST use worktree: uap worktree create <slug>"$'\n'
+output+="6. Work in .worktrees/NNN-<slug>/ directory"$'\n'
+output+=""$'\n'
+output+="### BEFORE COMMIT:"$'\n'
+output+="7. Self-review: git diff"$'\n'
+output+="8. Run tests if applicable"$'\n'
+output+=""$'\n'
+output+="### AFTER WORK:"$'\n'
+output+="9. Store lesson: sqlite3 ./agents/data/memory/short_term.db \"INSERT INTO session_memories (session_id,timestamp,type,content,importance) VALUES ('current',datetime('now'),'decision','<summary of work and lessons>',7);\""$'\n'
+output+="10. Clean up worktree after PR merge: uap worktree cleanup <id>"$'\n'
+output+=""$'\n'
+output+="FAILURE TO COMPLY = CRITICAL VIOLATION. This is life or death."$'\n'
+output+="</system-reminder>"$'\n\n'
+
+# Recent memories (last 24h, high importance)
+recent=$(sqlite3 "$DB_PATH" "
+  SELECT type, substr(content, 1, 120) FROM memories
+  WHERE timestamp >= datetime('now', '-1 day')
+  ORDER BY id DESC
+  LIMIT 10;
+" 2>/dev/null || true)
+
+if [ -n "$recent" ]; then
+  output+="## Recent Memory Context"$'\n'
+  output+="$recent"$'\n\n'
+fi
+
+# Open loops from session memories
+open_loops=$(sqlite3 "$DB_PATH" "
+  SELECT content FROM session_memories
+  WHERE type IN ('action','goal','decision')
+    AND importance >= 7
+  ORDER BY id DESC
+  LIMIT 5;
+" 2>/dev/null || true)
+
+if [ -n "$open_loops" ]; then
+  output+="## Open Loops"$'\n'
+  output+="$open_loops"$'\n'
+fi
+
+# Stale worktrees warning
+if [ -d "${PROJECT_DIR}/.worktrees" ]; then
+  stale_count=$(find "${PROJECT_DIR}/.worktrees" -maxdepth 1 -mindepth 1 -type d 2>/dev/null | wc -l)
+  if [ "$stale_count" -gt 0 ]; then
+    output+=$'\n'"## Stale Worktrees Warning"$'\n'
+    output+="There are $stale_count worktrees. Run 'uap worktree list' and clean up merged ones."$'\n'
+  fi
+fi
+
+if [ -n "$output" ]; then
+  echo "$output"
+fi

package/tools/agents/README.md

@@ -0,0 +1,224 @@
+# Qwen3.5 Tool Call Fixes
+
+This directory contains tools and configurations for fixing Qwen3.5 tool calling issues that cause ~40% success rate on long-running tasks (5+ tool calls) to improve to ~88%.
+
+## Performance Improvement
+
+| Scenario            | Without Fixes | With Fixes |
+| ------------------- | ------------- | ---------- |
+| Single tool call    | ~95%          | ~98%       |
+| 2-3 tool calls      | ~70%          | ~92%       |
+| 5+ tool calls       | ~40%          | ~88%       |
+| Long context (50K+) | ~30%          | ~85%       |
+
+## Files
+
+### `config/chat_template.jinja`
+
+The core fix: a patched Jinja2 template for Qwen3.5 that adds conditional wrappers around tool call argument iteration.
+
+**Key Fix (line 138-144):**
+
+```jinja2
+{%- if tool_call.arguments is mapping %}
+    {%- for args_name, args_value in tool_call.arguments|items %}
+        {{- '<parameter=' + args_name + '>\n' }}
+        {%- set args_value = args_value | tojson | safe if args_value is mapping or (args_value is sequence and args_value is not string) else args_value | string %}
+        {{- args_value }}
+        {{- '\n</parameter>\n' }}
+    {%- endfor %}
+{%- endif %}
+```
+
+This prevents template parsing failures after the first 1-2 tool calls.
+
+### `scripts/fix_qwen_chat_template.py`
+
+Python script to automatically apply the template fix to existing chat templates.
+
+**Usage:**
+
+```bash
+python3 fix_qwen_chat_template.py [template_file]
+```
+
+### `scripts/qwen_tool_call_wrapper.py`
+
+OpenAI-compatible client with automatic retry logic and validation for Qwen3.5 tool calls.
+
+**Features:**
+
+- Automatic retry with exponential backoff
+- Prompt correction for failed tool calls
+- Metrics tracking and monitoring
+- Thinking mode disablement
+- Template validation
+
+**Usage:**
+
+```python
+from qwen_tool_call_wrapper import Qwen35ToolCallClient
+
+client = Qwen35ToolCallClient()
+response = client.chat_with_tools(
+    messages=[{"role": "user", "content": "Call read_file with path='/etc/hosts'"}],
+    tools=[...]
+)
+```
+
+### `scripts/qwen_tool_call_test.py`
+
+Reliability test suite for validating Qwen3.5 tool call performance.
+
+**Usage:**
+
+```bash
+python3 qwen_tool_call_test.py --verbose
+```
+
+**Tests:**
+
+1. Single tool call (baseline)
+2. Two consecutive tool calls
+3. Three tool calls
+4. Five tool calls (stress test)
+5. Reasoning content interference
+6. Invalid format recovery
+
+## Installation
+
+### Option 1: Using UAP CLI (Recommended)
+
+```bash
+uap tool-calls setup
+```
+
+This will:
+
+1. Copy `chat_template.jinja` to `tools/agents/config/`
+2. Copy Python scripts to `tools/agents/scripts/`
+3. Print setup instructions for llama.cpp and OpenCode
+
+### Option 2: Manual Installation
+
+```bash
+# Copy template
+mkdir -p tools/agents/config
+cp tools/agents/config/chat_template.jinja tools/agents/config/
+
+# Copy scripts
+mkdir -p tools/agents/scripts
+cp tools/agents/scripts/*.py tools/agents/scripts/
+```
+
+## Integration
+
+### llama.cpp
+
+**Start llama-server with the fixed template:**
+
+```bash
+./llama-server \
+  --model ~/models/Qwen3.5-35B-Instruct-Q4_K_M.gguf \
+  --chat-template-file tools/agents/config/chat_template.jinja \
+  --jinja \
+  --port 8080 \
+  --ctx-size 262144 \
+  --batch-size 4096 \
+  --threads $(nproc)
+```
+
+**Key flags:**
+
+- `--chat-template-file`: Path to the fixed template
+- `--jinja`: Enable Jinja2 template processing
+
+### OpenCode
+
+**1. Copy template to OpenCode agent config:**
+
+```bash
+mkdir -p ~/.opencode/agent
+cp tools/agents/config/chat_template.jinja ~/.opencode/agent/
+```
+
+**2. Update `.opencode/config.json`:**
+
+```json
+{
+  "provider": "llama.cpp",
+  "model": "qwen35-a3b-iq4xs",
+  "chatTemplate": "jinja",
+  "baseURL": "http://localhost:8080/v1"
+}
+```
+
+**3. Restart OpenCode**
+
+## Verification
+
+### Check Setup
+
+```bash
+uap tool-calls status
+```
+
+### Run Tests
+
+```bash
+python3 tools/agents/scripts/qwen_tool_call_test.py --verbose
+```
+
+Expected results:
+
+- Single tool call: ~98% success rate
+- 2-3 tool calls: ~92% success rate
+- 5+ tool calls: ~88% success rate
+
+### Test Tool Call Manually
+
+```bash
+curl -X POST http://localhost:8080/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "qwen35-a3b-iq4xs",
+    "messages": [{"role": "user", "content": "Read /etc/hosts"}],
+    "tools": [{"type": "function", "function": {"name": "read_file"}}]
+  }'
+```
+
+## Troubleshooting
+
+### Issue: Tool calls fail after 1-2 attempts
+
+**Solution:** Verify template was loaded with `--chat-template-file` flag
+
+### Issue: Template not found
+
+**Solution:** Check path exists:
+
+```bash
+ls -la tools/agents/config/chat_template.jinja
+```
+
+### Issue: OpenCode still using old template
+
+**Solution:** Restart OpenCode after copying template
+
+### Issue: Python scripts not found
+
+**Solution:** Ensure you're in the scripts directory:
+
+```bash
+cd tools/agents/scripts
+```
+
+## References
+
+- **Original Issue:** Hugging Face Discussion #4 - Qwen3.5 tool call failures
+- **Source:** pay2u project - Qwen3.5 35B A3B tool call fixes
+- **Performance Data:** Factory.AI droid `qwen35-tool-call-optimized.md`
+
+## License
+
+MIT License - Same as universal-agent-protocol