High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: add root cause analysis of API misuse and solutions
Mario5ea7c64f3a6f
diff --git a/docs/API-MISUSE-ROOT-CAUSE-ANALYSIS.md b/docs/API-MISUSE-ROOT-CAUSE-ANALYSIS.mdnew file mode 100644index 00000000..692971b8--- /dev/null+++ b/docs/API-MISUSE-ROOT-CAUSE-ANALYSIS.md@@ -0,0 +1,293 @@+# Pinchtab API Misuse: Root Cause Analysis & Solutions++**Date:** February 27, 2026+**Summary:** Misunderstood Pinchtab API design led to silent failures. Root cause: inadequate documentation of API dependencies and workflows.++---++## The Problem++### What I Did Wrong+```bash+curl 'http://localhost:9867/snapshot?url=https://www.bbc.com&format=text'+ ↑+ This parameter doesn't exist!+```++### What Happened+- Endpoint exists: `/snapshot` ✓+- Parameter exists: `?format=text` ✓+- Parameter `?url=...` does NOT exist ✗+- API returned 200 OK (not an error!)+- But with no tabId → defaulted to current tab (blank)+- Result: `about:blank` response (silent failure)++### Why It Was Confusing+I didn't get an error. The API returned valid JSON:+```json+{+ "title": "",+ "url": "about:blank"+}+```++This looked like Pinchtab was broken, not like I was using the API wrong.++---++## Root Cause: Documentation Gaps++### Problem 1: API Reference Assumes Too Much Context++**File:** `skill/pinchtab/references/api.md`++**Current documentation:**+```bash+# Snapshot (accessibility tree)+curl /snapshot++# Interactive elements only+curl "/snapshot?filter=interactive"++# Limit depth+curl "/snapshot?depth=5"+```++**Why it's misleading:**+- Shows isolated examples without dependencies+- Doesn't mention `?tabId=...` (required parameter!)+- No examples using `?tabId=X`+- Implies you can just call `/snapshot` and get page content+- Agent's mental model: "snapshot is like web_fetch, takes a URL"++**Missing context:**+- You CANNOT: `curl /snapshot?url=https://...`+- You MUST: `curl /snapshot?tabId=<ID>&url=...` (and tabId comes from elsewhere)+- Where does tabId come from? → Not explained in this section++---++### Problem 2: Tab Management Section Exists But Isn't Connected++**File:** `skill/pinchtab/references/api.md` (later in the document)++**Current documentation:**+```bash+# Tab management+curl /tabs++# Open new tab+curl -X POST /tab -H 'Content-Type: application/json' \+ -d '{"action": "new", "url": "https://example.com"}'++# Close tab+curl -X POST /tab -H 'Content-Type: application/json' \+ -d '{"action": "close", "tabId": "TARGET_ID"}'+```++**Problem:**+- Shows how to CREATE a tab and get `tabId`+- But `/snapshot` section (earlier) doesn't reference this+- No explicit: "After creating a tab, use this tabId with /snapshot"+- Two sections that need each other aren't connected++---++### Problem 3: SKILL.md Conceptual But Not Practical++**File:** `skill/pinchtab/SKILL.md`++**Current documentation:**+```markdown+# Core Workflow: Actual API Calls++The typical agent loop:++1. **Navigate** to a URL+2. **Snapshot** the accessibility tree (get refs)+3. **Act** on refs (click, type, press)+```++**Problem:**+- "Navigate to a URL" — but which endpoint?+ - `/navigate` (POST) — navigates current tab+ - `/tab {"action":"new","url":"..."}` (POST) — creates new tab+ - Documentation doesn't clarify the difference!+- "Snapshot the accessibility tree" — assumes you already know you need a tabId+- Missing the `→ curl` examples that show actual sequencing++---++## The Correct API Flow++### Step-by-Step (What Actually Works)++```bash+# ✅ STEP 1: Create tab + navigate (returns tabId)+curl -X POST http://localhost:9867/tab \+ -H "Content-Type: application/json" \+ -d '{"action":"new","url":"https://www.bbc.com","timeout":10}'++# Response:+# {+# "tabId": "7A2578741782B5C085640C984F511358",+# "title": "BBC - Home",+# "url": "https://www.bbc.co.uk/"+# }++# ✅ STEP 2: Use tabId to get snapshot+curl "http://localhost:9867/snapshot?tabId=7A2578741782B5C085640C984F511358&format=text&maxTokens=2000"++# Response:+# # BBC - Home+# # https://www.bbc.co.uk/+# # 149 nodes+#+# e0 RootWebArea "BBC - Home" [focused]+# e1 banner+# e2 main+# ... (semantic accessibility tree with clickable refs)+```++### Why This Design?++Pinchtab is **tab-centric**, not URL-centric:+- `/snapshot` operates on a tab, not a URL+- Multiple tabs can exist simultaneously+- Each tab has its own state, navigation history, cookies+- Need to specify WHICH tab you're working with → `?tabId=X`++This is correct design (matches CDP/browser model), but the documentation doesn't explain the "why".++---++## Solutions Implemented++### 1. **New Wrapper Script: `scripts/pinchtab-curl-wrapper.sh`**++Hides complexity behind simple commands:+```bash+# Instead of:+# Step 1: Create tab, extract tabId+# Step 2: Call /snapshot with tabId+# Step 3: Parse JSON, act on result++# Just use:+./pinchtab-curl-wrapper.sh text https://www.bbc.com+./pinchtab-curl-wrapper.sh snapshot https://www.bbc.com compact+./pinchtab-curl-wrapper.sh click https://www.bbc.com e5+```++**What it does:**+- Handles tab creation internally+- Manages tabId flow+- Provides clean CLI+- Error handling+- Color output++---++### 2. **Updated Documentation**++#### In `pinchtab-clean-slate.md`+- Added "Validation Method" section explaining API flow+- Included sample response showing structure+- Clarified why Pinchtab returns refs (e0, e1...) not just text+- Provided working curl examples++#### In PR Description+- "Root Cause Analysis" section+- Actual curl examples+- Explanation of why it failed++#### Recommendations for Future Docs+1. Add **"Workflow Examples"** section BEFORE API reference+2. Show complete end-to-end examples:+ ```markdown+ ### Example 1: Extract Text from a URL+ - Use: /tab to create tab+ - Then: /text to extract++ ### Example 2: Get Refs and Click Elements+ - Use: /tab to create tab+ - Then: /snapshot to get refs (e0, e1...)+ - Then: /action to click a ref+ - Then: /snapshot again to see result+ ```++3. Add "Why This Design?" sections explaining:+ - Why /snapshot needs tabId (tab-centric, not URL-centric)+ - How it differs from web_fetch or OpenClaw (which are stateless)+ - When to use /navigate vs /tab?action=new++---++## Lessons Learned++### For API Design+- **Document the dependencies**, not just the endpoints+- **Show complete workflows** in addition to isolated commands+- **Explain the "why"** — why is it tab-centric? Why not just pass URL?+- **Connect related sections** (Tab Management + Snapshot)++### For API Usage+- **Read the entire reference**, not just the section you think you need+- **Look for examples showing sequencing** (step 1, step 2, step 3)+- **Try the wrapper/CLI first** before raw HTTP if it exists+- **Debug silently by checking assumptions** — "is my tabId valid?" not "is the API broken?"++### For Documentation+- **Isolate reference docs** (api.md) from **practical guides** (getting-started.md)+- **Use workflow diagrams** showing dependencies+- **Include "common mistakes"** section++---++## Real Data: Pinchtab is Excellent++Once you use it correctly:++| Metric | Value |+|--------|-------|+| Response size | 7.3-7.7 KB |+| Tokens per page | 1,834-1,934 |+| Includes JavaScript rendering | ✓ |+| Returns clickable refs | ✓ (e0, e1, e2...) |+| vs OpenClaw snapshot | 27x lighter |+| vs web_fetch | 3.1-3.6x lighter |++The API is well-designed. The documentation just needs a getting-started section.++---++## Files Included++- `API-MISUSE-ROOT-CAUSE-ANALYSIS.md` (this file)+- `scripts/pinchtab-curl-wrapper.sh` (solution)+- `pinchtab-clean-slate.md` (with empirical data + proper examples)+- PR #52 with complete benchmark data++---++## Recommendations++### Short Term (PR Ready)+- ✅ Add wrapper script+- ✅ Update benchmark docs with real data+- ✅ Document the proper API flow in pinchtab-clean-slate.md++### Medium Term (Next Release)+- [ ] Add "Workflow Examples" section to api.md+- [ ] Add Getting-Started guide (different from reference docs)+- [ ] Add "Common Mistakes" section+- [ ] Update SKILL.md with actual curl examples+- [ ] Add "Why This Design?" boxes++### Long Term+- [ ] Consider CLI-first approach (users learn \`pinchtab\` CLI before HTTP)+- [ ] Add interactive tutorial: \`pinchtab interactive-tutorial\`+- [ ] Add validation tool: \`pinchtab validate-setup\` (checks Pinchtab is running, port is open, etc.)++---++**Bottom line:** The Pinchtab API is solid. The documentation just needs to show HOW to use it in addition to WHAT endpoints exist.