@uzysjung/agent-harness 26.136.0 → 26.139.0

package/templates/skills/gemini-consult/scripts/gemini-ask.sh

@@ -4,14 +4,22 @@
 # on stdout, wrapped in <untrusted-gemini-output> tags; progress → stderr.
 #
 # Usage:
-#   gemini-ask.sh [-m "MODEL"] "PROMPT"           # text (Korean polish / persona review)
-#   gemini-ask.sh [-m "MODEL"] <<'EOF'            # multi-line prompt via stdin
+#   gemini-ask.sh [-t TIER] [-m MODEL] "PROMPT"     # text (Korean polish / persona review)
+#   gemini-ask.sh [-t TIER] [-m MODEL] <<'EOF'      # multi-line prompt via stdin
 #   ...multi-line prompt...
 #   EOF
-#   gemini-ask.sh -g OUT_DIR [-m "MODEL"] "PROMPT"  # image gen: files copied to OUT_DIR
-#   gemini-ask.sh -- "-leading-dash prompt"       # `--` ends option parsing
+#   gemini-ask.sh -g OUT_DIR [-t TIER] "PROMPT"     # image gen: files copied to OUT_DIR
+#   gemini-ask.sh -- "-leading-dash prompt"         # `--` ends option parsing
 #
-# Exit codes: 2 usage · 3 agy missing · 4 secret-shaped prompt refused ·
+# TIER (default: pro) selects a model FAMILY; the concrete model is resolved
+# from `agy models` at call time, so no version string is pinned in here:
+#   pro    — gemini-*-pro-*   : every Gemini call this skill makes
+#   claude — claude-*         : a non-Gemini reply, or the Gemini quota is spent
+# `-m SLUG` skips tier resolution entirely — pass an exact slug from
+# `agy models`, or a custom model configured in agy's settings.
+#
+# Exit codes: 2 usage · 3 agy missing / no model matches TIER ·
+#             4 secret-shaped prompt refused ·
 #             5 image mode produced no files · 124 timed out ·
 #             otherwise agy's own exit code.
 #
@@ -25,20 +33,22 @@
 set -euo pipefail
 
 AGY="${AGY_BIN:-$(command -v agy || echo "$HOME/.local/bin/agy")}"
-# The "gemini 3.1 pro" the user asked for. Override with -m or GEMINI_CONSULT_MODEL.
-# See `agy models` for the full list (e.g. "Gemini 3.1 Pro (Low)" is faster).
-MODEL="${GEMINI_CONSULT_MODEL:-Gemini 3.1 Pro (High)}"
+# Pick a FAMILY (see resolution below), never a version. Empty MODEL means
+# "resolve TIER against `agy models`"; a non-empty one is used verbatim.
+TIER="${GEMINI_CONSULT_TIER:-pro}"
+MODEL="${GEMINI_CONSULT_MODEL:-}"
 TIMEOUT_S="${GEMINI_CONSULT_TIMEOUT:-300}"
 # Where agy drops generated artifacts (images land here, not in cwd, because
 # headless mode denies the shell "command" permission a cwd-save would need).
 BRAIN_DIR="${GEMINI_CONSULT_BRAIN:-$HOME/.gemini/antigravity-cli/brain}"
 OUTDIR=""
 
-while getopts "m:g:" opt; do
+while getopts "m:g:t:" opt; do
   case "$opt" in
     m) MODEL="$OPTARG" ;;
     g) OUTDIR="$OPTARG" ;;
-    *) echo 'usage: gemini-ask.sh [-m "MODEL"] [-g OUT_DIR] "PROMPT"' >&2; exit 2 ;;
+    t) TIER="$OPTARG" ;;
+    *) echo 'usage: gemini-ask.sh [-t pro|claude] [-m MODEL] [-g OUT_DIR] "PROMPT"' >&2; exit 2 ;;
   esac
 done
 shift $((OPTIND - 1))
@@ -99,9 +109,62 @@ fi
 # Neutral cwd → agy won't pull the current repo into its workspace context.
 WORKDIR="$(mktemp -d)"
 MSGFILE="$(mktemp)"
-trap 'rm -rf "$WORKDIR" "$MSGFILE" ${MARKER:+"$MARKER"}' EXIT
+MODELS_ERR=""
+trap 'rm -rf "$WORKDIR" "$MSGFILE" ${MARKER:+"$MARKER"} ${MODELS_ERR:+"$MODELS_ERR"}' EXIT
 cd "$WORKDIR"
 
+# Tier → concrete model, resolved from `agy models` on every call. Pinning a
+# version here rots: agy retires slugs (an unknown one dies with "invalid model
+# selection", exit 1), and the families do NOT share a version line — measured
+# 2026-07-26, a flash line was 3.6 while pro was still 3.1 — so neither "newest" nor
+# "best" can be spelled as a constant.
+if [ -z "$MODEL" ]; then
+  case "$TIER" in
+    pro) TIER_RE='^gemini-.*-pro(-|$)' ;;
+    claude) TIER_RE='^claude-' ;;
+    *) echo "gemini-ask.sh: unknown tier '$TIER' (expected pro | claude; use -m for an exact slug)" >&2; exit 2 ;;
+  esac
+  MODELS_ERR="$(mktemp)"
+  MODELS="$(env -i PATH="$PATH" HOME="$HOME" TERM="${TERM:-dumb}" "$AGY" models 2>"$MODELS_ERR")" || MODELS=""
+  # Rank candidates: version desc, then capability (opus > sonnet), then effort
+  # (high/thinking > medium > low). Digits are read positionally so both slug
+  # shapes rank alike — `gemini-3.1-pro-high` and `claude-opus-4-6-thinking`.
+  # Fixed-width keys mean a plain `sort -r` suffices (BSD sort has no -V), and
+  # `awk NR==1` (not `head -1`) avoids a SIGPIPE under `set -o pipefail`.
+  MODEL="$(printf '%s\n' "$MODELS" | grep -E "$TIER_RE" | awk -F- '
+    {
+      maj = 0; min = 0; qual = 0; eff = 0
+      for (i = 1; i <= NF; i++) {
+        if ($i ~ /^[0-9]+(\.[0-9]+)?$/) {
+          if (maj == 0) { split($i, v, "."); maj = v[1] + 0; min = v[2] + 0 }
+          else if (min == 0) { min = $i + 0 }
+        }
+        if ($i == "opus") qual = 2
+        else if ($i == "sonnet") qual = 1
+        if ($i == "high" || $i == "thinking") eff = 3
+        else if ($i == "medium") eff = 2
+        else if ($i == "low") eff = 1
+      }
+      printf "%03d%03d%d%d %s\n", maj, min, qual, eff, $0
+    }' | sort -r | awk 'NR == 1 { print $2 }')" || MODEL=""
+  if [ -z "$MODEL" ]; then
+    # Never silently fall back to some other tier: the caller asked for this
+    # family for a reason, and a wrong-family answer looks like a right one.
+    echo "gemini-ask.sh: no '$TIER' model offered by \`agy models\` — available:" >&2
+    printf '%s\n' "$MODELS" | sed 's/^/  /' >&2
+    if [ -s "$MODELS_ERR" ]; then
+      # Surface agy's own stderr — an auth/network failure here looks exactly
+      # like "tier not offered" if you only see the empty list.
+      echo "gemini-ask.sh: \`agy models\` stderr:" >&2
+      cat "$MODELS_ERR" >&2
+    fi
+    exit 3
+  fi
+  echo "gemini-ask.sh: tier '$TIER' → model '$MODEL'" >&2
+else
+  echo "gemini-ask.sh: model '$MODEL' (explicit)" >&2
+fi
+
 # Env allowlist: don't hand agy ambient tokens (GH_TOKEN, AWS_*, ...). HOME
 # stays so agy auth (~/.gemini) keeps working.
 # NOTE: --model must precede -p, and the prompt must be the value right after

package/templates/skills/ui-visual-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ui-visual-review
-description: "Captures screenshots of key UI flows after E2E tests pass, runs an agent-side first-pass diff (regressions, console errors, layout shifts), then surfaces a checklist for the user's final approval. Use after E2E tests pass on a UI track (csr-*, ssr-*, full)."
+description: "Captures screenshots of key UI flows after E2E tests pass, runs an agent-side first-pass diff (regressions, console errors, layout shifts), then surfaces a checklist for the user's final approval. Also owns the browser-launch procedure the `playwright-launch` rule delegates here: use it whenever a browser must be opened for a human to drive or for automated capture — manual E2E checks, UX/fidelity comparison against a reference product, or a one-time OAuth login. Use after E2E tests pass on a UI track (csr-*, ssr-*, full)."
 ---
 
 # UI Visual Review
@@ -31,6 +31,56 @@ E2E 테스트가 PASS 했어도 시각적 회귀(layout shift, 색상/간격 변
 - 앱이 로컬에서 기동 가능 (예: `pnpm dev`, `docker-compose up`)
 - 핵심 화면 URL 리스트가 정의됨 (없으면 본 skill 첫 실행 시 사용자 질의)
 
+## 브라우저를 띄우는 법 (영속 profile)
+
+`playwright-launch` 룰이 **금지**를 소유하고, 여기가 **절차**를 소유한다. 금지문은 상주해야
+하지만(위반은 작업 도중에 일어난다) 아래 절차는 실제로 브라우저를 띄울 때만 필요하다.
+
+핵심은 셋이다. ⓐ **영속 profile dir** — 프로젝트별로 분리해 매 iteration 재사용한다. cookie ·
+IndexedDB · Service Worker 가 보존돼야 재로그인이 사라진다. ⓑ **Chrome for Testing 별도 binary**
+(`npx playwright install chromium`) — 사용자의 일반 Chrome 과 완전히 분리한다. ⓒ **사용자가 키를
+입력하는 동안 자동화 layer 0** — main session 은 창을 띄우기만 하고, capture·검증은 입력이 끝난 뒤
+별도 process 에서 돈다.
+
+```js
+import { chromium } from 'playwright';
+
+const PROFILE_DIR = process.env.PROJECT_PROFILE_DIR || `${process.env.HOME}/.<project>-audit-profile`;
+const TARGET = process.env.PROJECT_URL || 'http://localhost:<port>';
+
+const ctx = await chromium.launchPersistentContext(PROFILE_DIR, {
+  headless: false,
+  viewport: { width: 1440, height: 900 },
+  args: ['--disable-blink-features=AutomationControlled', '--no-first-run', '--no-default-browser-check'],
+});
+const page = ctx.pages()[0] ?? (await ctx.newPage());
+
+// (선택) dev bypass auth — OAuth 의 webdriver 차단을 피한다. same-origin cookie 로 저장된다.
+await page.goto(`${TARGET}/`, { waitUntil: 'domcontentloaded' });
+await ctx.request.post(`${TARGET}/api/v1/_dev/test-login`, {
+  data: { key: process.env.E2E_TEST_KEY ?? 'e2e-dev-key', email: 'e2e@example.local' },
+});
+await page.reload({ waitUntil: 'networkidle' });
+
+// 창을 띄운 채 자동화는 detach — 사용자가 직접 쓴다. ctx.close() 를 부르지 않는다.
+```
+
+**두 가지 사용 형태**
+
+0. **기존 launcher 를 먼저 정리한다** — `pkill -f "playwright|Chrome for Testing"`. 같은 profile
+   dir 을 잡고 있는 창이 살아 있으면 `launchPersistentContext` 가 기동하지 못한다. 첫 실행은 되고
+   **2회차부터** 실패하기 때문에 프로필 잠금이 아니라 스크립트 버그로 오진하기 쉽다.
+1. **사용자가 직접 보는 경우** — `node scripts/<project>-launch.mjs` 를 포그라운드로 띄우고
+   "URL / 로그인됨 / 직접 쓰세요"를 보고한 뒤, 추가 navigation·evaluate 를 **하지 않는다**.
+   사용자 입력과 충돌한다.
+2. **자동 capture (fidelity·audit)** — 같은 `launchPersistentContext` 로 시나리오를 자동 click 하고
+   산출물을 `docs/research/<area>_audit_<sprint>/iter_<N>/` 에 남긴다.
+
+> **이 launcher 로 띄운 창은 Playwright API 로 캡처한다**(`page.screenshot({ fullPage: true })`,
+> 콘솔은 `page.on('console')`). 아래 §2·§4 의 chrome-devtools MCP 예시는 launcher 없이 MCP 로
+> 작업하는 경우다 — Playwright 는 CDP 를 파이프로 물어 외부 프로세스가 붙을 엔드포인트를 열지
+> 않으므로, 이 둘을 한 세션에서 섞으려 하면 붙을 대상이 없다. **하나를 고르고 끝까지 그걸로 간다.**
+
 ## Process
 
 ### 1. 화면 리스트업 (한 번만)