@miller-tech/uap 1.0.0

package/templates/hooks/session-start.sh

@@ -0,0 +1,366 @@
+#!/usr/bin/env bash
+# UAP Session Start Hook (universal - all coding harnesses)
+# 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:-${FACTORY_PROJECT_DIR:-${CURSOR_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
+
+# Auto-create coordination DB if missing (self-healing)
+if [ ! -f "$COORD_DB" ]; then
+  mkdir -p "$(dirname "$COORD_DB")"
+  sqlite3 "$COORD_DB" "
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA busy_timeout = 10000;
+
+    CREATE TABLE IF NOT EXISTS agent_registry (
+      id TEXT PRIMARY KEY, name TEXT NOT NULL, session_id TEXT NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('active','idle','completed','failed')),
+      current_task TEXT, worktree_branch TEXT, started_at TEXT NOT NULL,
+      last_heartbeat TEXT NOT NULL, capabilities TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_agent_registry_session ON agent_registry(session_id);
+    CREATE INDEX IF NOT EXISTS idx_agent_registry_status ON agent_registry(status);
+
+    CREATE TABLE IF NOT EXISTS agent_messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, channel TEXT NOT NULL,
+      from_agent TEXT, to_agent TEXT,
+      type TEXT NOT NULL CHECK(type IN ('request','response','notification','claim','release')),
+      payload TEXT NOT NULL, priority INTEGER DEFAULT 5,
+      created_at TEXT NOT NULL, read_at TEXT, expires_at TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_messages_channel ON agent_messages(channel);
+    CREATE INDEX IF NOT EXISTS idx_messages_to_agent ON agent_messages(to_agent);
+    CREATE INDEX IF NOT EXISTS idx_messages_created ON agent_messages(created_at);
+
+    CREATE TABLE IF NOT EXISTS work_announcements (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, agent_id TEXT NOT NULL,
+      agent_name TEXT, worktree_branch TEXT,
+      intent_type TEXT NOT NULL CHECK(intent_type IN ('editing','reviewing','refactoring','testing','documenting')),
+      resource TEXT NOT NULL, description TEXT, files_affected TEXT,
+      estimated_completion TEXT, announced_at TEXT NOT NULL, completed_at TEXT,
+      FOREIGN KEY (agent_id) REFERENCES agent_registry(id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_announcements_agent ON work_announcements(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_announcements_resource ON work_announcements(resource);
+    CREATE INDEX IF NOT EXISTS idx_announcements_active ON work_announcements(completed_at) WHERE completed_at IS NULL;
+
+    CREATE TABLE IF NOT EXISTS work_claims (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, resource TEXT NOT NULL,
+      agent_id TEXT NOT NULL, claim_type TEXT NOT NULL CHECK(claim_type IN ('exclusive','shared')),
+      claimed_at TEXT NOT NULL, expires_at TEXT,
+      FOREIGN KEY (agent_id) REFERENCES agent_registry(id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_claims_agent ON work_claims(agent_id);
+    CREATE INDEX IF NOT EXISTS idx_claims_resource ON work_claims(resource);
+
+    CREATE TABLE IF NOT EXISTS deploy_queue (
+      id INTEGER PRIMARY KEY AUTOINCREMENT, agent_id TEXT NOT NULL,
+      action_type TEXT NOT NULL CHECK(action_type IN ('commit','push','merge','deploy','workflow')),
+      target TEXT NOT NULL, payload TEXT,
+      status TEXT NOT NULL CHECK(status IN ('pending','batched','executing','completed','failed')),
+      batch_id TEXT, queued_at TEXT NOT NULL, execute_after TEXT,
+      priority INTEGER DEFAULT 5, dependencies TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_deploy_status ON deploy_queue(status);
+    CREATE INDEX IF NOT EXISTS idx_deploy_batch ON deploy_queue(batch_id);
+    CREATE INDEX IF NOT EXISTS idx_deploy_target ON deploy_queue(target);
+
+    CREATE TABLE IF NOT EXISTS deploy_batches (
+      id TEXT PRIMARY KEY, created_at TEXT NOT NULL, executed_at TEXT,
+      status TEXT NOT NULL CHECK(status IN ('pending','executing','completed','failed')),
+      result TEXT
+    );
+  " 2>/dev/null || true
+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
+
+# ============================================================
+# MANDATORY: Auto-register this agent + start heartbeat
+# ============================================================
+AGENT_ID="claude-${SESSION_ID:-$(head -c 6 /dev/urandom | od -An -tx1 | tr -d ' \n')}"
+AGENT_NAME="claude-code"
+
+if [ -f "$COORD_DB" ]; then
+  # Register this agent
+  sqlite3 "$COORD_DB" "
+    INSERT OR REPLACE INTO agent_registry (id, name, session_id, status, capabilities, started_at, last_heartbeat)
+    VALUES ('${AGENT_ID}', '${AGENT_NAME}', '${AGENT_ID}', 'active', '[]', datetime('now'), datetime('now'));
+  " 2>/dev/null || true
+
+  # Check for other active agents and their work
+  OTHER_AGENTS=$(sqlite3 "$COORD_DB" "
+    SELECT id || ': ' || COALESCE(current_task, 'idle')
+    FROM agent_registry
+    WHERE status='active' AND id != '${AGENT_ID}'
+    ORDER BY last_heartbeat DESC LIMIT 5;
+  " 2>/dev/null || true)
+
+  ACTIVE_WORK=$(sqlite3 "$COORD_DB" "
+    SELECT agent_id || ' -> ' || resources
+    FROM work_announcements
+    WHERE completed_at IS NULL
+    ORDER BY announced_at DESC LIMIT 5;
+  " 2>/dev/null || true)
+fi
+
+# Export agent ID for downstream tools
+export UAP_AGENT_ID="${AGENT_ID}"
+
+# Start background heartbeat (every 30s, auto-stops when shell exits)
+if [ -f "$COORD_DB" ]; then
+  (
+    while true; do
+      sleep 30
+      sqlite3 "$COORD_DB" "UPDATE agent_registry SET last_heartbeat=datetime('now') WHERE id='${AGENT_ID}';" 2>/dev/null || break
+    done
+  ) &
+  HEARTBEAT_PID=$!
+  # Ensure heartbeat stops and agent deregisters on exit
+  trap "kill $HEARTBEAT_PID 2>/dev/null; sqlite3 \"$COORD_DB\" \"UPDATE agent_registry SET status='completed' WHERE id='${AGENT_ID}';\" 2>/dev/null" EXIT
+fi
+
+output=""
+
+# ============================================================
+# UAP SESSION BANNER - Rich Operational Data
+# ============================================================
+SESSION_ID=$(head -c 6 /dev/urandom | od -An -tx1 | tr -d ' \n' | head -c 6)
+TASK_DB="${PROJECT_DIR}/.uap/tasks/tasks.db"
+PKG_VERSION=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('${PROJECT_DIR}/package.json','utf8')).version)}catch{console.log('?')}" 2>/dev/null || echo "?")
+
+# Gather task stats
+TASK_TOTAL=0; TASK_OPEN=0; TASK_PROGRESS=0; TASK_BLOCKED=0; TASK_DONE=0
+if [ -f "$TASK_DB" ]; then
+  TASK_TOTAL=$(sqlite3 "$TASK_DB" "SELECT COUNT(*) FROM tasks;" 2>/dev/null || echo 0)
+  TASK_OPEN=$(sqlite3 "$TASK_DB" "SELECT COUNT(*) FROM tasks WHERE status='open';" 2>/dev/null || echo 0)
+  TASK_PROGRESS=$(sqlite3 "$TASK_DB" "SELECT COUNT(*) FROM tasks WHERE status='in_progress';" 2>/dev/null || echo 0)
+  TASK_BLOCKED=$(sqlite3 "$TASK_DB" "SELECT COUNT(*) FROM tasks WHERE status='blocked';" 2>/dev/null || echo 0)
+  TASK_DONE=$(sqlite3 "$TASK_DB" "SELECT COUNT(*) FROM tasks WHERE status='done' OR status='wont_do';" 2>/dev/null || echo 0)
+fi
+
+# Gather memory stats
+MEM_ENTRIES=0; MEM_SIZE="0 KB"
+if [ -f "$DB_PATH" ]; then
+  MEM_ENTRIES=$(sqlite3 "$DB_PATH" "SELECT COUNT(*) FROM memories;" 2>/dev/null || echo 0)
+  MEM_SIZE=$(du -h "$DB_PATH" 2>/dev/null | cut -f1 || echo "?")
+fi
+
+# Gather agent stats
+AGENT_COUNT=0
+if [ -f "$COORD_DB" ]; then
+  AGENT_COUNT=$(sqlite3 "$COORD_DB" "SELECT COUNT(*) FROM agent_registry WHERE status='active';" 2>/dev/null || echo 0)
+fi
+
+# Qdrant status
+QDRANT_STATUS="OFF"
+if docker ps --filter name=qdrant --format "{{.Status}}" 2>/dev/null | grep -q "Up"; then
+  QDRANT_STATUS="ON"
+fi
+
+# Git branch
+GIT_BRANCH=$(git -C "$PROJECT_DIR" branch --show-current 2>/dev/null || echo "?")
+GIT_DIRTY=$(git -C "$PROJECT_DIR" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+# Worktree count
+WORKTREE_COUNT=0
+if [ -d "${PROJECT_DIR}/.worktrees" ]; then
+  WORKTREE_COUNT=$(find "${PROJECT_DIR}/.worktrees" -maxdepth 1 -mindepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
+fi
+
+# Pattern count
+PATTERN_COUNT=0
+if [ -f "${PROJECT_DIR}/.factory/patterns/index.json" ]; then
+  PATTERN_COUNT=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('${PROJECT_DIR}/.factory/patterns/index.json','utf8')).patterns?.length||0)}catch{console.log(0)}" 2>/dev/null || echo 0)
+fi
+
+# Skill count
+SKILL_COUNT=$(find "${PROJECT_DIR}/.claude/skills" "${PROJECT_DIR}/.factory/skills" -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
+
+# Droid count
+DROID_COUNT=$(find "${PROJECT_DIR}/.factory/droids" -name "*.md" -not -name "test-droid-*" 2>/dev/null | wc -l | tr -d ' ')
+
+# Build task progress bar (20 chars wide)
+if [ "$TASK_TOTAL" -gt 0 ]; then
+  TASK_PCT=$((TASK_DONE * 100 / TASK_TOTAL))
+  FILLED=$((TASK_DONE * 20 / TASK_TOTAL))
+  EMPTY=$((20 - FILLED))
+  TASK_BAR=$(printf '%0.s█' $(seq 1 $FILLED 2>/dev/null) 2>/dev/null)$(printf '%0.s░' $(seq 1 $EMPTY 2>/dev/null) 2>/dev/null)
+else
+  TASK_PCT=0
+  TASK_BAR="░░░░░░░░░░░░░░░░░░░░"
+fi
+
+# Render banner
+W=62
+output+="╭$(printf '─%.0s' $(seq 1 $W))╮"$'\n'
+output+="│ UAP  Universal Agent Protocol  v${PKG_VERSION}$(printf ' %.0s' $(seq 1 $((W - 40 - ${#PKG_VERSION}))))│"$'\n'
+output+="│ Session: ${SESSION_ID}  $(date '+%Y-%m-%d %H:%M:%S')  Branch: ${GIT_BRANCH}$(printf ' %.0s' $(seq 1 $((W - 42 - ${#GIT_BRANCH}))))│"$'\n'
+output+="├$(printf '─%.0s' $(seq 1 $W))┤"$'\n'
+
+# Task status line
+if [ "$TASK_TOTAL" -gt 0 ]; then
+  output+="│ Tasks: ${TASK_BAR} ${TASK_PCT}% (${TASK_DONE}/${TASK_TOTAL})$(printf ' %.0s' $(seq 1 $((W - 38 - ${#TASK_PCT} - ${#TASK_DONE} - ${#TASK_TOTAL}))))│"$'\n'
+  TASK_DETAIL="${TASK_OPEN} open  ${TASK_PROGRESS} active  ${TASK_BLOCKED} blocked  ${TASK_DONE} done"
+  output+="│   ${TASK_DETAIL}$(printf ' %.0s' $(seq 1 $((W - 3 - ${#TASK_DETAIL}))))│"$'\n'
+else
+  output+="│ Tasks: No tasks tracked yet$(printf ' %.0s' $(seq 1 $((W - 28))))│"$'\n'
+fi
+
+# Memory & infrastructure line
+MEM_LINE="Memory: ${MEM_ENTRIES} entries (${MEM_SIZE})  Qdrant: ${QDRANT_STATUS}"
+output+="│ ${MEM_LINE}$(printf ' %.0s' $(seq 1 $((W - 1 - ${#MEM_LINE}))))│"$'\n'
+
+# Agents, patterns, skills line
+INFRA_LINE="Agents: ${AGENT_COUNT}  Patterns: ${PATTERN_COUNT}  Skills: ${SKILL_COUNT}  Droids: ${DROID_COUNT}"
+output+="│ ${INFRA_LINE}$(printf ' %.0s' $(seq 1 $((W - 1 - ${#INFRA_LINE}))))│"$'\n'
+
+# Git & worktree line
+GIT_LINE="Git: ${GIT_DIRTY} uncommitted  Worktrees: ${WORKTREE_COUNT}"
+output+="│ ${GIT_LINE}$(printf ' %.0s' $(seq 1 $((W - 1 - ${#GIT_LINE}))))│"$'\n'
+
+output+="├$(printf '─%.0s' $(seq 1 $W))┤"$'\n'
+
+# Active policies
+output+="│ Policies: [ON] IaC Parity  [ON] File Backup$(printf ' %.0s' $(seq 1 $((W - 47))))│"$'\n'
+
+# Memory layers
+L3_STATUS="?"
+[ "$QDRANT_STATUS" = "ON" ] && L3_STATUS="ON"
+output+="│ Layers:  L1:ON  L2:ON  L3:${L3_STATUS}  L4:ON$(printf ' %.0s' $(seq 1 $((W - 37 - ${#L3_STATUS}))))│"$'\n'
+
+output+="╰$(printf '─%.0s' $(seq 1 $W))╯"$'\n'
+output+=""$'\n'
+
+# ============================================================
+# 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+="### BEFORE FIRST EDIT (MANDATORY):"$'\n'
+output+="5. BACKUP all files you will modify: cp <file> .uap-backups/$(date +%Y-%m-%d)/<file>"$'\n'
+output+="   Or use: mkdir -p .uap-backups/$(date +%Y-%m-%d) && cp -r <dir> .uap-backups/$(date +%Y-%m-%d)/"$'\n'
+output+=""$'\n'
+output+="### DURING WORK:"$'\n'
+output+="6. ALL file changes MUST use worktree: uap worktree create <slug>"$'\n'
+output+="7. Work in .worktrees/NNN-<slug>/ directory"$'\n'
+output+=""$'\n'
+output+="### BEFORE COMMIT:"$'\n'
+output+="8. Self-review: git diff"$'\n'
+output+="9. Run tests if applicable"$'\n'
+output+=""$'\n'
+output+="### AFTER WORK:"$'\n'
+output+="10. 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+="11. Clean up worktree after PR merge: uap worktree cleanup <id>"$'\n'
+output+=""$'\n'
+output+="### MULTI-AGENT COORDINATION (MANDATORY):"$'\n'
+output+="Your agent ID is: ${AGENT_ID}"$'\n'
+output+="12. Before editing files, announce work: uap agent announce --resources '<file1>,<file2>' --description '<what>'"$'\n'
+output+="13. Check for conflicts: uap agent overlaps"$'\n'
+output+="14. After completing work: uap agent complete <announcement-id>"$'\n'
+output+=""$'\n'
+
+if [ -n "$OTHER_AGENTS" ]; then
+  output+="### ACTIVE AGENTS (coordinate with them):"$'\n'
+  output+="$OTHER_AGENTS"$'\n'
+  output+=""$'\n'
+fi
+
+if [ -n "$ACTIVE_WORK" ]; then
+  output+="### ACTIVE WORK ANNOUNCEMENTS (avoid conflicts):"$'\n'
+  output+="$ACTIVE_WORK"$'\n'
+  output+=""$'\n'
+fi
+
+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
+  mem_count=$(echo "$recent" | wc -l)
+  output+="[MEMORY] ${mem_count} recent memories loaded (last 24h)"$'\n'
+  output+="## Recent Memory Context"$'\n'
+  output+="$recent"$'\n\n'
+else
+  output+="[MEMORY] No recent memories found (last 24h)"$'\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
+
+# In-progress tasks (show what's actively being worked on)
+if [ -f "$TASK_DB" ] && [ "$TASK_PROGRESS" -gt 0 ]; then
+  active_tasks=$(sqlite3 "$TASK_DB" "SELECT '  [' || id || '] ' || title FROM tasks WHERE status='in_progress' ORDER BY priority ASC LIMIT 5;" 2>/dev/null || true)
+  if [ -n "$active_tasks" ]; then
+    output+="## Active Tasks"$'\n'
+    output+="$active_tasks"$'\n'
+  fi
+fi
+
+# Blocked tasks warning
+if [ -f "$TASK_DB" ] && [ "$TASK_BLOCKED" -gt 0 ]; then
+  blocked_tasks=$(sqlite3 "$TASK_DB" "SELECT '  [' || id || '] ' || title FROM tasks WHERE status='blocked' ORDER BY priority ASC LIMIT 3;" 2>/dev/null || true)
+  if [ -n "$blocked_tasks" ]; then
+    output+=$'\n'"## Blocked Tasks (need attention)"$'\n'
+    output+="$blocked_tasks"$'\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:** universal-agent-protocol 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