Agentation

{
  "skill_name": "agentation",
  "evals": [
    {
      "id": 1,
      "prompt": "I can click the broken CTA in the running app, leave a note, and I want the agent to patch the exact component without guessing which button I mean.",
      "expected_output": "Chooses agentation as the UI annotation bridge, recommends a copy-paste or synced review mode, and keeps browser-runtime choice separate.",
      "assertions": [
        "Selects agentation for exact rendered-UI feedback",
        "Mentions structured annotation packets or exact UI targeting",
        "Does not misroute the task to plannotator as the primary skill"
      ]
    },
    {
      "id": 2,
      "prompt": "Run a repeatable headless checkout verification and compare the result in a clean browser session.",
      "expected_output": "Routes away from agentation to agent-browser because deterministic fresh-session verification is the real job.",
      "assertions": [
        "Routes to agent-browser or an equivalent fresh-session browser verifier",
        "Explains that agentation is not the primary tool for deterministic browser verification"
      ]
    },
    {
      "id": 3,
      "prompt": "Wire the annotation queue into Claude Code so pending UI notes show up automatically every time I send a message.",
      "expected_output": "Chooses agentation platform setup mode, mentions MCP registration plus the Claude hook/injection path, and includes verification guidance.",
      "assertions": [
        "Selects agentation platform setup or watch-loop mode",
        "Mentions MCP registration or agentation-mcp",
        "Mentions verifying the setup before trusting the loop"
      ]
    },
    {
      "id": 4,
      "prompt": "Open the proposed implementation plan in a browser so I can approve or reject changes before coding starts.",
      "expected_output": "Routes away from agentation to plannotator because the review target is a plan/diff rather than a rendered UI issue.",
      "assertions": [
        "Routes to plannotator or equivalent plan review skill",
        "Explains that agentation is for rendered UI feedback, not plan approval"
      ]
    }
  ]
}

#!/usr/bin/env bash
# setup-agentation-mcp.sh — Register agentation MCP server for all AI agent platforms
#
# Usage:
#   bash setup-agentation-mcp.sh           # all platforms
#   bash setup-agentation-mcp.sh --claude  # Claude Code only
#   bash setup-agentation-mcp.sh --codex   # Codex CLI only
#   bash setup-agentation-mcp.sh --gemini  # Gemini CLI only
#   bash setup-agentation-mcp.sh --opencode # OpenCode only
#   bash setup-agentation-mcp.sh --all     # all platforms (explicit)

set -euo pipefail

RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; BLUE='\033[0;34m'; NC='\033[0m'
info()  { echo -e "${BLUE}ℹ  $*${NC}"; }
ok()    { echo -e "${GREEN}✅ $*${NC}"; }
warn()  { echo -e "${YELLOW}⚠  $*${NC}"; }
err()   { echo -e "${RED}✗  $*${NC}" >&2; }

# ─── Argument parsing ────────────────────────────────────────────────────────
SETUP_CLAUDE=false
SETUP_CODEX=false
SETUP_GEMINI=false
SETUP_OPENCODE=false

while [[ $# -gt 0 ]]; do
  case "$1" in
    --claude)   SETUP_CLAUDE=true ;;
    --codex)    SETUP_CODEX=true ;;
    --gemini)   SETUP_GEMINI=true ;;
    --opencode) SETUP_OPENCODE=true ;;
    --all)      SETUP_CLAUDE=true; SETUP_CODEX=true; SETUP_GEMINI=true; SETUP_OPENCODE=true ;;
    *) warn "Unknown flag: $1" ;;
  esac
  shift
done

# Default: all platforms
if [[ "$SETUP_CLAUDE$SETUP_CODEX$SETUP_GEMINI$SETUP_OPENCODE" == "falsefalsefalsefalse" ]]; then
  SETUP_CLAUDE=true; SETUP_CODEX=true; SETUP_GEMINI=true; SETUP_OPENCODE=true
fi

echo "╔══════════════════════════════════════════╗"
echo "║  agentation MCP Setup                    ║"
echo "╚══════════════════════════════════════════╝"
echo ""

# ─── Claude Code (~/.claude/claude_desktop_config.json) ───────────────────
if [[ "$SETUP_CLAUDE" == "true" ]]; then
  info "Setting up Claude Code..."
  CLAUDE_DIR="$HOME/.claude"
  CLAUDE_CFG="$CLAUDE_DIR/claude_desktop_config.json"
  mkdir -p "$CLAUDE_DIR"

  MCP_JSON='{"command":"npx","args":["-y","agentation-mcp","server"]}'

  if [[ -f "$CLAUDE_CFG" ]]; then
    if command -v jq &>/dev/null; then
      MERGED=$(jq --argjson entry "$MCP_JSON" '.mcpServers.agentation = $entry' "$CLAUDE_CFG" 2>/dev/null)
      if [[ -n "$MERGED" ]]; then
        echo "$MERGED" > "$CLAUDE_CFG"
        ok "Claude Code: merged into $CLAUDE_CFG"
      else
        warn "Claude Code: jq merge failed — add manually"
      fi
    else
      warn "Claude Code: jq not found — add manually to $CLAUDE_CFG:"
      echo '  "mcpServers": { "agentation": { "command": "npx", "args": ["-y", "agentation-mcp", "server"] } }'
    fi
  else
    cat > "$CLAUDE_CFG" <<'EOF'
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}
EOF
    ok "Claude Code: created $CLAUDE_CFG"
  fi
  echo ""
fi

# ─── Codex CLI (~/.codex/config.toml) ─────────────────────────────────────
if [[ "$SETUP_CODEX" == "true" ]]; then
  info "Setting up Codex CLI..."
  CODEX_DIR="$HOME/.codex"
  CODEX_CFG="$CODEX_DIR/config.toml"
  mkdir -p "$CODEX_DIR"

  CODEX_ENTRY=$'\n# agentation MCP Server\n[[mcp_servers]]\nname = "agentation"\ncommand = "npx"\nargs = ["-y", "agentation-mcp", "server"]\n'

  if [[ -f "$CODEX_CFG" ]]; then
    if grep -q '"agentation"\|name = "agentation"' "$CODEX_CFG" 2>/dev/null; then
      warn "Codex CLI: agentation already in $CODEX_CFG — skipping"
    else
      printf '%s' "$CODEX_ENTRY" >> "$CODEX_CFG"
      ok "Codex CLI: appended to $CODEX_CFG"
    fi
  else
    printf '%s' "$CODEX_ENTRY" > "$CODEX_CFG"
    ok "Codex CLI: created $CODEX_CFG"
  fi
  echo ""
fi

# ─── Gemini CLI (~/.gemini/settings.json) ─────────────────────────────────
if [[ "$SETUP_GEMINI" == "true" ]]; then
  info "Setting up Gemini CLI..."
  GEMINI_DIR="$HOME/.gemini"
  GEMINI_CFG="$GEMINI_DIR/settings.json"
  mkdir -p "$GEMINI_DIR"

  MCP_JSON='{"command":"npx","args":["-y","agentation-mcp","server"]}'

  if [[ -f "$GEMINI_CFG" ]]; then
    if command -v jq &>/dev/null; then
      MERGED=$(jq --argjson entry "$MCP_JSON" '.mcpServers.agentation = $entry' "$GEMINI_CFG" 2>/dev/null)
      if [[ -n "$MERGED" ]]; then
        echo "$MERGED" > "$GEMINI_CFG"
        ok "Gemini CLI: merged into $GEMINI_CFG"
      else
        warn "Gemini CLI: jq merge failed — add manually"
      fi
    else
      warn "Gemini CLI: jq not found — add manually to $GEMINI_CFG:"
      echo '  "mcpServers": { "agentation": { "command": "npx", "args": ["-y", "agentation-mcp", "server"] } }'
    fi
  else
    cat > "$GEMINI_CFG" <<'EOF'
{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}
EOF
    ok "Gemini CLI: created $GEMINI_CFG"
  fi
  echo ""
fi

# ─── OpenCode (~/.config/opencode/opencode.json) ──────────────────────────
if [[ "$SETUP_OPENCODE" == "true" ]]; then
  info "Setting up OpenCode..."
  OC_DIR="$HOME/.config/opencode"
  OC_CFG="$OC_DIR/opencode.json"
  mkdir -p "$OC_DIR"

  MCP_ENTRY='{"type":"local","command":["npx","-y","agentation-mcp","server"]}'

  if [[ -f "$OC_CFG" ]]; then
    if command -v jq &>/dev/null; then
      MERGED=$(jq --argjson entry "$MCP_ENTRY" '.mcp.agentation = $entry' "$OC_CFG" 2>/dev/null)
      if [[ -n "$MERGED" ]]; then
        echo "$MERGED" > "$OC_CFG"
        ok "OpenCode: merged into $OC_CFG"
      else
        warn "OpenCode: jq merge failed — add manually"
      fi
    else
      warn "OpenCode: jq not found — add manually to $OC_CFG:"
      echo '  "mcp": { "agentation": { "type": "local", "command": ["npx", "-y", "agentation-mcp", "server"] } }'
    fi
  else
    cat > "$OC_CFG" <<'EOF'
{
  "mcp": {
    "agentation": {
      "type": "local",
      "command": ["npx", "-y", "agentation-mcp", "server"]
    }
  }
}
EOF
    ok "OpenCode: created $OC_CFG"
  fi
  echo ""
fi

# ─── Done ─────────────────────────────────────────────────────────────────
echo "╔══════════════════════════════════════════╗"
echo "║  Setup Complete                          ║"
echo "╚══════════════════════════════════════════╝"
echo ""
echo "Next steps:"
echo "  1. Restart your agent(s)"
echo "  2. Start agentation MCP server:  npx agentation-mcp server"
echo "  3. Add to your app:              import { Agentation } from 'agentation'"
echo "     <Agentation endpoint=\"http://localhost:4747\" />"
echo ""
echo "Available MCP tools: agentation_watch_annotations, agentation_resolve, agentation_acknowledge, ..."
echo "Run 'npx agentation-mcp doctor' to verify."

#!/usr/bin/env bash
# verify-loop.sh — Integration test for agentation watch loop
# Tests: server health, annotation CRUD, ACK-RESOLVE cycle, error cases
# Usage: bash verify-loop.sh [--quick]   (--quick skips phase 4 error tests)
set -euo pipefail

GREEN='\033[0;32m'; RED='\033[0;31m'; YELLOW='\033[1;33m'; NC='\033[0m'
pass() { echo -e "${GREEN}PASS${NC} $*"; }
fail() { echo -e "${RED}FAIL${NC} $*"; FAILURES=$((FAILURES + 1)); }
info() { echo -e "${YELLOW}....${NC} $*"; }

FAILURES=0
BASE_URL="http://localhost:4747"
QUICK=false
[[ "${1:-}" == "--quick" ]] && QUICK=true

echo ""
echo "agentation Watch Loop — Integration Test"
echo "========================================="
echo ""

# ── Phase 1: Server Health ──────────────────────────────────────────────────

echo "Phase 1: Server Health"
echo "──────────────────────"

info "1a. Health check"
if curl -sf --connect-timeout 3 "${BASE_URL}/health" >/dev/null 2>&1; then
  pass "GET /health — server reachable"
else
  fail "GET /health — server not reachable. Start with: npx agentation-mcp server"
  echo ""
  echo "Cannot continue without server. Exiting."
  exit 1
fi

info "1b. Status check"
STATUS=$(curl -sf "${BASE_URL}/status" 2>/dev/null || echo "")
if [[ -n "$STATUS" ]]; then
  pass "GET /status — returns server metadata"
else
  fail "GET /status — empty response"
fi

info "1c. Baseline pending check"
PENDING=$(curl -sf "${BASE_URL}/pending" 2>/dev/null || echo '{"count":-1}')
BASELINE_COUNT=$(echo "$PENDING" | python3 -c "import sys,json; print(json.load(sys.stdin).get('count',-1))" 2>/dev/null || echo -1)
if [[ "$BASELINE_COUNT" -ge 0 ]]; then
  pass "GET /pending — baseline count: ${BASELINE_COUNT}"
else
  fail "GET /pending — invalid response"
fi

echo ""

# ── Phase 2: Session & Annotation CRUD ──────────────────────────────────────

echo "Phase 2: Annotation CRUD"
echo "────────────────────────"

info "2a. Create session"
SESSION_RESP=$(curl -sf -X POST "${BASE_URL}/sessions" -H "Content-Type: application/json" -d '{}' 2>/dev/null || echo "")
SESSION_ID=$(echo "$SESSION_RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || echo "")
if [[ -n "$SESSION_ID" ]]; then
  pass "POST /sessions — created session: ${SESSION_ID:0:12}..."
else
  fail "POST /sessions — failed to create session"
  echo "Cannot continue without session. Exiting."
  exit 1
fi

info "2b. Create annotation"
ANN_RESP=$(curl -sf -X POST "${BASE_URL}/sessions/${SESSION_ID}/annotations" \
  -H "Content-Type: application/json" \
  -d "{\"comment\":\"Test: change button color\",\"element\":\"button\",\"elementPath\":\"body > main > button.cta\",\"x\":50,\"y\":100}" 2>/dev/null || echo "")
ANN_ID=$(echo "$ANN_RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || echo "")
if [[ -n "$ANN_ID" ]]; then
  pass "POST annotation — created: ${ANN_ID:0:12}..."
else
  fail "POST annotation — failed"
fi

info "2c. Verify pending count = 1"
P_COUNT=$(curl -sf "${BASE_URL}/sessions/${SESSION_ID}/pending" 2>/dev/null \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('count',0))" 2>/dev/null || echo 0)
if [[ "$P_COUNT" -eq 1 ]]; then
  pass "GET /sessions/:id/pending — count: 1"
else
  fail "GET /sessions/:id/pending — expected 1, got ${P_COUNT}"
fi

echo ""

# ── Phase 3: ACK-RESOLVE Cycle ──────────────────────────────────────────────

echo "Phase 3: ACK-RESOLVE Cycle"
echo "──────────────────────────"

info "3a. Acknowledge annotation"
ACK_RESP=$(curl -sf -X PATCH "${BASE_URL}/annotations/${ANN_ID}" \
  -H "Content-Type: application/json" \
  -d '{"status":"acknowledged"}' 2>/dev/null || echo "")
ACK_STATUS=$(echo "$ACK_RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',''))" 2>/dev/null || echo "")
if [[ "$ACK_STATUS" == "acknowledged" ]]; then
  pass "PATCH acknowledged — status: acknowledged"
else
  fail "PATCH acknowledged — expected 'acknowledged', got '${ACK_STATUS}'"
fi

info "3b. Resolve annotation"
RES_RESP=$(curl -sf -X PATCH "${BASE_URL}/annotations/${ANN_ID}" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved","resolution":"Changed button color to #3b82f6"}' 2>/dev/null || echo "")
RES_STATUS=$(echo "$RES_RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',''))" 2>/dev/null || echo "")
if [[ "$RES_STATUS" == "resolved" ]]; then
  pass "PATCH resolved — status: resolved"
else
  fail "PATCH resolved — expected 'resolved', got '${RES_STATUS}'"
fi

info "3c. Verify pending count = 0"
FINAL_COUNT=$(curl -sf "${BASE_URL}/sessions/${SESSION_ID}/pending" 2>/dev/null \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('count',0))" 2>/dev/null || echo -1)
if [[ "$FINAL_COUNT" -eq 0 ]]; then
  pass "GET pending after resolve — count: 0 (all resolved)"
else
  fail "GET pending after resolve — expected 0, got ${FINAL_COUNT}"
fi

echo ""

# ── Phase 4: Error Cases ────────────────────────────────────────────────────

if ! $QUICK; then
  echo "Phase 4: Error Cases"
  echo "────────────────────"

  info "4a. Invalid annotation ID"
  HTTP_CODE=$(curl -sf -o /dev/null -w "%{http_code}" -X PATCH "${BASE_URL}/annotations/nonexistent-id-12345" \
    -H "Content-Type: application/json" -d '{"status":"acknowledged"}' 2>/dev/null || echo "000")
  if [[ "$HTTP_CODE" == "404" || "$HTTP_CODE" == "400" ]]; then
    pass "Invalid ID — HTTP ${HTTP_CODE} (expected 4xx)"
  else
    fail "Invalid ID — expected 4xx, got HTTP ${HTTP_CODE}"
  fi

  info "4b. GET non-existent session"
  HTTP_CODE=$(curl -sf -o /dev/null -w "%{http_code}" "${BASE_URL}/sessions/nonexistent-session-12345" 2>/dev/null || echo "000")
  if [[ "$HTTP_CODE" == "404" || "$HTTP_CODE" == "400" ]]; then
    pass "Non-existent session — HTTP ${HTTP_CODE} (expected 4xx)"
  else
    fail "Non-existent session — expected 4xx, got HTTP ${HTTP_CODE}"
  fi

  echo ""
fi

# ── Summary ─────────────────────────────────────────────────────────────────

echo "========================================="
if [[ "$FAILURES" -eq 0 ]]; then
  echo -e "${GREEN}ALL TESTS PASSED${NC}"
  echo ""
  echo "agentation watch loop is working correctly."
  echo "MCP tool agentation_watch_annotations should function end-to-end."
else
  echo -e "${RED}${FAILURES} TEST(S) FAILED${NC}"
  echo ""
  echo "Fix the issues above and re-run: bash verify-loop.sh"
fi
echo ""
exit $FAILURES

N:agentation D:"Capture exact rendered-UI feedback and hand it to an agent as selectors, element paths, and structured annotation packets. Use when a human needs to point at a real UI issue, run a sync/watch loop, or wire browser feedback into Claude Code, Codex, Gemini CLI, or OpenCode. Not for fresh-session browser verification (agent-browser), running-browser reuse (playwriter), or plan/diff approval (plannotator)." T:Read|Write|Bash|Grep|Glob P:planning-review/agentation G:ui-feedback|browser-annotation|visual-feedback|mcp|react|ai-agent|design-review|css-selector