@kahinmcp/kahin 0.3.9 → 0.3.10

package/CHANGELOG.md

@@ -2,11 +2,64 @@
 
 ## Unreleased
 
-## [0.3.9] — 2026-08-08
-
+## [0.3.10] — 2026-08-09
+
+- fix(harness): align lifecycle tests and screenshot measure with grace-window runtime
+- fix(stealth): disable Camoufox humanize mouse trajectory (drops acks, wedges input)
+- fix(release): retry npm pack verification after publish
+- chore: prepare v0.3.9
+- chore: refresh packaged kahin wheel
+- fix: harden single-engine crawler runtime
+- fix: preserve crawler rotation state
+- feat: add single-engine crawler rotation
+- docs: define crawler identity rotation contract
+- fix: harden Kahin browser runtime
 - update
 - ci(release): tolerate npm registry propagation
 
+## [0.3.9] — 2026-08-09
+
+### Eklenen
+- `kahin_crawl_start` / `kahin_crawl_status` / `kahin_crawl_results` /
+  `kahin_crawl_pause` / `kahin_crawl_resume` / `kahin_crawl_stop` eklendi:
+  tek aktif Camoufox/Mirage motoru ve tek mevcut sekme üzerinde çalışan,
+  bounded kuyruk/sonuç günlüğü ve cursor destekli crawler yüzeyi.
+- Crawler; sayfa, derinlik, süre ve gecikme bütçelerini sınırlar, `Retry-After`
+  ile rate-limit durumunda bounded backoff uygular ve otomatik identity
+  rotasyonunu aynı browser/sekme yaşam döngüsü içinde yürütür.
+
+### Düzeltilen
+- Aktif motor yeniden kullanılmadan tekrar browser açılması, degraded health
+  durumunda canlı context'in gereksiz değiştirilmesi ve crawler sırasında
+  sekmenin kaybolması engellendi.
+- Sidecar stdin yazımları ve sayfa işlemleri bounded hale getirildi; engine
+  çökmesi sonrası URL yeniden kuyruğa alınarak aynı crawler işi kontrollü
+  recovery ile sürdürülebilir hale geldi.
+- Humanized mouse trajectory artık Juggler'ın tamamlamadığı aynı-koordinat
+  no-op dispatch'ini göndermiyor; gerçek hareket adımı korunuyor.
+- CAPTCHA ve erişim engeli bypass edilmiyor: crawler challenge'ı açıkça
+  `paused` durumuna geçiriyor ve ajan müdahalesi için aynı işi koruyor.
+- Her rotation gerçek per-launch fingerprint değişimiyle doğrulanıyor;
+  proxy/geo ayarları ve kayıtlı identity kullanımı yeniden başlatma/rotasyon
+  sonrasında korunuyor.
+- Proxy ile başlatma için Camoufox'un `geoip` extra'sı paket bağımlılığına
+  alındı; temiz kurulumlar artık native proxy/geo ayarını eksik modül yüzünden
+  başarısız bırakmıyor. GeoIP endpoint'i erişilemezse proxy korunarak
+  proxy-only launch fallback'i uygulanıyor.
+- npm launcher wheel install marker'ı ve Camoufox hazırlığı bounded komut
+  süreleriyle tekrar kurulumları güvenli ve hızlı hale getiriyor.
+
+### Gerçek doğrulama
+- Paketlenmiş stdio MCP ile 146 tool ve 2 resource list/read doğrulandı.
+- Gerçek crawler akışında tek engine PID ve tek sekme ile 4 sayfa başarıyla
+  işlendi, 4 rotation gerçekleşti; rate-limit ve CAPTCHA challenge durumları
+  tekrar çağrılarda tutarlı biçimde korundu.
+- Gerçek engine kill sonrası crawler 1 recovery attempt ile 5 başarılı sayfayı
+  tamamladı; ayrı identity probe'unda her rotation fingerprint hash'i değişti.
+- Dış web sayfasında stealth audit `14/14`, DOM snapshot/event reset-dropped,
+  accessibility tree ve `browser_stop` sonrası parent MCP transport bağlantısı
+  doğrulandı.
+
 ## [0.3.8] — 2026-08-08
 
 ### Eklenen
@@ -311,3 +364,4 @@ Tüm önemli değişiklikler bu dosyada tutulur. Format: [Keep a Changelog](http
 [0.3.7]: https://gitlab.com/void0x14/kahin-mcp/-/compare/v0.3.6...v0.3.7
 [0.3.8]: https://gitlab.com/void0x14/kahin-mcp/-/compare/v0.3.7...v0.3.8
 [0.3.9]: https://gitlab.com/void0x14/kahin-mcp/-/compare/v0.3.8...v0.3.9
+[0.3.10]: https://gitlab.com/void0x14/kahin-mcp/-/compare/v0.3.9...v0.3.10

package/README.md

@@ -16,7 +16,7 @@ AI modeller Chrome'un içine girip sayfa gezip kod çalıştırabilir ama CDP'yi
 
 56 domain, 667 komut, 237 event, 609 type — Chrome 148 protokolü gömülü.
 
-## 139 Tool · 4 Kategori Ailesi · 2 Engine
+## 146 Tool · 5 Kategori Ailesi · 2 Engine
 
 Tool'lar engine-ayrımlı kategori dosyalarında (`kahin/tools/`): paylaşılan çekirdek + Obscura + Camoufox aileleri.
 
@@ -29,10 +29,11 @@ Tool'lar engine-ayrımlı kategori dosyalarında (`kahin/tools/`): paylaşılan
 |  DEJA_VU — Debug | CDP event geçmişi, network istekleri, console mesajları | 4 |
 |  PROPHECY — Pattern DB | Kullanım desenlerini öğren, sorgula, öner | 5 |
 |  HEALER | Hata istatistikleri | 1 |
-|  MIRAGE — Camoufox Native (107) | Juggler protokolü üstünde gerçek-zamanlı DOM stream, DOM, Reliability, Input, PageEx, Tab, Network, Storage, Emulation, Dialog/Download/Worker/WS, Upload, Screencast, Accessibility, Engine sağlığı/istatistik, Agent-native snapshot/form/state/identity/status, Stealth audit/insansı girdi/identity rotasyonu/proxy-geo | 107 |
+|  MIRAGE — Camoufox Native (104) | Juggler protokolü üstünde gerçek-zamanlı DOM stream, DOM, Reliability, Input, PageEx, Tab, Network, Storage, Emulation, Dialog/Download/Worker/WS, Upload, Screencast, Accessibility, Engine sağlığı/istatistik, Agent-native snapshot/form/state/identity/status/challenge, Stealth audit/insansı girdi/identity rotasyonu/proxy-geo | 104 |
+|  ORBIT — Long Crawler (6) | Tek Mirage browser/tab üzerinde bounded background crawl, sonuç cursor'ı, rate-limit backoff, challenge pause/resume, rotation ve cancel | 6 |
 |  OBSCURA — Ayrı kategori | Obscura'ya özel tool'lar (hazırlanıyor) | 0 |
 
-**Toplam: 139 tool.**
+**Toplam: 146 tool.**
 
 ## Bir satırda özet
 
@@ -104,14 +105,17 @@ Camoufox (Juggler native) ile:
 → kahin_mirage_query("#btn", frame_id="subframe-...")   # iframe içi erişim
 → kahin_mirage_cookie_set/get/clear → kahin_mirage_storage_local_get
 → kahin_mirage_set_user_agent / set_viewport / set_geolocation
-→ kahin_mirage_set_file_chooser_intercept(true) → kahin_mirage_upload_files(["/abs/path"])
+→ kahin_mirage_set_file_chooser_intercept(true)
+→ (eşzamanlı) kahin_mirage_upload_files(["/abs/path"]) + kahin_mirage_click("input[type=file]")
 → kahin_mirage_screencast_start → kahin_mirage_screencast_frame (base64 JPEG)
 → kahin_mirage_accessibility_tree → kahin_engine_health → kahin_engine_stats
 → kahin_mirage_dom_start → kahin_mirage_dom_snapshot → kahin_mirage_dom_events
 → kahin_mirage_dom_action (snapshot'tan alınan canlı nodeId ile)
 → kahin_mirage_snapshot (ref'li ajan görünümü) → kahin_mirage_fill_form
 → kahin_mirage_state_save/load → kahin_identity_new/save/list/delete/report
-→ kahin_agent_status (agent döngüsü özeti)
+→ kahin_agent_status (agent döngüsü özeti) → kahin_challenge_status (crawl öncesi)
+→ kahin_crawl_start(seeds=[...]) → kahin_crawl_status → kahin_crawl_results(cursor=...)
+→ kahin_crawl_pause/resume/stop
 ```
 
 `kahin_browser_start` tek bir Camoufox/sidecar süreci açar. İlk sayfa işlemi
@@ -120,6 +124,20 @@ bu sekmeyi yeniden kullanır. Ayrı bir sayfa gerektiğinde yeni tarayıcı baş
 yerine `kahin_mirage_tab_new` ve `kahin_mirage_tab_switch` kullanın. Camoufox
 aktifken `kahin_execute_cdp` ve diğer CDP araçları, eşdeğer Juggler/Mirage
 çağrısına otomatik yönlendirilir ve CDP biçimli sonuç döndürür.
+Makine genelinde aktif browser slot'u lock ile korunur; ikinci bağımsız MCP
+süreci ikinci browser açmak yerine owner bilgisini içeren `engine_process_conflict`
+döndürür. Native navigation hedefi bounded response timeout'a takılırsa Kahin
+aynı browser/context içinde yalnızca hedef tab'ı yenileyebilir; başarılı recovery
+`target_recovered: true` olarak raporlanır ve browser PID'si değişmez.
+
+Uzun süreli yetkili crawl için `kahin_crawl_start` background job başlatır ve
+MCP çağrısını açık tutmaz. Job aynı Camoufox browser'ı ve crawler tab'ını yeniden
+kullanır; varsayılan rotation 20 başarılı sayfa veya 15 dakikadır. Her rotation
+sayfa ledger'a yazıldıktan sonra gerçekleşir ve yeni BrowserForge fingerprint'i
+gerçek bir Camoufox restart'ında üretilir. `kahin_crawl_results` bounded cursor
+ile sonuçları parça parça verir. 429/503 için Retry-After ve capped backoff
+uygulanır; CAPTCHA veya access-denied görülürse job pause olur. Kahin challenge
+bypass veya otomatik CAPTCHA çözümü yapmaz.
 
 Tam liste için: [AGENTS.md](AGENTS.md). Juggler'ın ajan sözleşmesi ve gerçek-zamanlı
 DOM akışı için [AI-native Juggler kılavuzuna](docs/juggler-ai-native.md) bakın.
@@ -161,7 +179,7 @@ Kahin'de hata loglama ve kendini onarma sistemi gömülüdür:
 
 ```
 oracle.py               → MCP server (bootstrap: mcp instance + engine lifecycle + main)
-  tools/                → 139 tool, engine-ayrımlı kategori dosyaları
+  tools/                → 140 tool, engine-ayrımlı kategori dosyaları
     _common.py          → capability routing, _safe_cdp, _require_engine, _auto_learn
     the_twins/capabilities → motor-yetenek sözleşmesi ve Mirage yükseltme matrisi
     grimoire/seraph/prophecy/healer → CDP bilgi + doğrulama + pattern (paylaşılan)
@@ -190,7 +208,7 @@ camoufox-harness/       → Zig sidecar (Juggler protocol, vendor binary gömül
 - [x] **Tek tık kurulum** — `pnpm add -g @kahinmcp/kahin`, sonra `kahin` (ilk çalıştırmada Python ortamını otomatik kurar)
 - [ ] **Zero-dependency** hedefi (Go/Rust portu)
 - [ ] **LSP modu** — kod içinde hata yakalama, AI'a yanlışını yüzüne vurma
-- [x] **Tool sayısı 139** — Camoufox Juggler-native 107 tool (gerçek-zamanlı DOM stream, DOM, Reliability, Input, Network, Storage, Emulation, Dialog, Tab, Worker/WS, Upload, Screencast, Accessibility, Engine sağlığı/istatistik, Agent-native snapshot/form/state/identity/status, Stealth audit/humanized input/identity pins/proxy geo) + paylaşılan 32 çekirdek
+- [x] **Tool sayısı 140** — Camoufox Juggler-native 104 tool (gerçek-zamanlı DOM stream, DOM, Reliability, Input, Network, Storage, Emulation, Dialog, Tab, Worker/WS, Upload, Screencast, Accessibility, Engine sağlığı/istatistik, Agent-native snapshot/form/state/identity/status, Stealth audit/humanized input/identity pins/proxy geo) + paylaşılan 36 çekirdek
 - [x] **Faz 4 performans yüzeyi** — non-blocking Zig sidecar (N=20 probe: paralel duvar 56.89 → 8.71 ms, ratio 1.314 → 3.281), `kahin_engine_stats` (monotonic uptime + per-tool rollup, top_slow ≤ 10) ve identity başına bounded prewarm metadata (launch asla atlanmaz; dürüst reuse kaydı)
 - [ ] **Obscura ayrı tool'ları** — CDP-yeteneklerine özel pilot_obscura/trainman_obscura/dejavu_obscura kategorilerini doldur
 

package/bin/kahin.mjs

@@ -5,7 +5,18 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+// A local pnpm link can point PACKAGE_ROOT at a checkout that contains a
+// ``kahin/`` source directory. Running ``python -m kahin.oracle`` with that
+// checkout as cwd shadows the wheel installed in the launcher's venv and
+// makes the same MCP command behave differently depending on the caller's
+// cwd. Use an empty system temp cwd for that development-link case; published
+// npm packages have no source directory and can run from their package root.
+const PYTHON_CWD = existsSync(join(PACKAGE_ROOT, "kahin")) ? tmpdir() : PACKAGE_ROOT;
 
 const HOME = process.env.KAHIN_HOME || join(homedir(), ".local", "share", "kahin");
 const VENV = join(HOME, "venv");
@@ -32,7 +43,10 @@ async function setup() {
     process.exit(1);
   }
   const python = existsSync(PY) ? PY : (process.env.KAHIN_PY || "python3");
-  const check = await sh(python, ["-c", "import kahin"], { stdio: ["ignore", "pipe", "pipe"] });
+  const check = await sh(python, ["-c", "import kahin"], {
+    stdio: ["ignore", "pipe", "pipe"],
+    cwd: PYTHON_CWD,
+  });
   if (check !== 0) {
     process.stderr.write(`[kahin] kahin Python paketi bulunamadı. ${python} ile çalıştırılamıyor.\n`);
     process.exit(1);
@@ -55,7 +69,10 @@ if (args[0] === "setup") {
 }
 
 const python = await setup();
-const child = spawn(python, ["-m", "kahin.oracle", ...args], { stdio: "inherit" });
+const child = spawn(python, ["-m", "kahin.oracle", ...args], {
+  stdio: "inherit",
+  cwd: PYTHON_CWD,
+});
 child.on("exit", (code, signal) => {
   if (signal) process.kill(process.pid, signal);
   process.exit(code ?? 0);

package/bin/setup.mjs

@@ -7,7 +7,7 @@
 // Client listesi, otomatik tespit yapan sistemlerden derlendi (add-mcp 15 ajan,
 // everymcp 15, mcpm 20+, getmcp 19, mcp-get 9, mcpkit): 22 client.
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { spawn } from "node:child_process";
@@ -324,7 +324,38 @@ export function setup() {
 const KAHIN_HOME = process.env.KAHIN_HOME || join(homedir(), ".local", "share", "kahin");
 const KAHIN_VENV = join(KAHIN_HOME, "venv");
 const KAHIN_PY = process.platform === "win32" ? join(KAHIN_VENV, "Scripts", "python.exe") : join(KAHIN_VENV, "bin", "python");
-const KAHIN_WHEEL = join(dirname(fileURLToPath(import.meta.url)), "..", "lib", "kahin-0.3.9-py3-none-any.whl");
+const KAHIN_WHEEL = join(dirname(fileURLToPath(import.meta.url)), "..", "lib", "kahin-0.3.10-py3-none-any.whl");
+const KAHIN_INSTALL_MARKER = join(KAHIN_HOME, ".install-state.json");
+const SETUP_COMMAND_TIMEOUT_MS = 120_000;
+
+function wheelStamp() {
+  try {
+    const info = statSync(KAHIN_WHEEL);
+    return `${info.size}:${Math.trunc(info.mtimeMs)}`;
+  } catch {
+    return null;
+  }
+}
+
+function installMarkerMatches(stamp) {
+  if (!stamp || !existsSync(KAHIN_INSTALL_MARKER)) return false;
+  try {
+    const marker = JSON.parse(readFileSync(KAHIN_INSTALL_MARKER, "utf8"));
+    return marker && marker.wheel === stamp && marker.python === KAHIN_PY;
+  } catch {
+    return false;
+  }
+}
+
+function writeInstallMarker(stamp) {
+  if (!stamp) return;
+  try {
+    mkdirSync(KAHIN_HOME, { recursive: true });
+    writeFileSync(KAHIN_INSTALL_MARKER, JSON.stringify({ wheel: stamp, python: KAHIN_PY }) + "\n");
+  } catch (err) {
+    process.stderr.write(`[kahin] install marker yazılamadı: ${err.message}\n`);
+  }
+}
 
 // Gömülü wheel'i venv'e kurar ve varsayılan Camoufox binary'sini hazırlar.
 // PyPI'a bağımlı DEĞİL — wheel paketle birlikte gelir; wheel'in bağımlılıkları
@@ -349,20 +380,39 @@ export async function installPython() {
       return { error: code };
     }
   }
-  log(`wheel kuruluyor: ${KAHIN_WHEEL}`);
-  const code = await run(KAHIN_PY, ["-m", "pip", "install", "--upgrade", KAHIN_WHEEL]);
-  if (code !== 0) {
-    log(`wheel kurulamadı (çıkış ${code})`);
-    return { error: code };
+  const stamp = wheelStamp();
+  if (installMarkerMatches(stamp)) {
+    log("Kahin wheel zaten güncel; pip kurulumu atlandı");
+  } else {
+    log(`wheel kuruluyor: ${KAHIN_WHEEL}`);
+    const code = await run(
+      KAHIN_PY,
+      ["-m", "pip", "install", "--upgrade", KAHIN_WHEEL],
+      SETUP_COMMAND_TIMEOUT_MS,
+    );
+    if (code !== 0) {
+      log(`wheel kurulamadı (çıkış ${code})`);
+      return { error: code };
+    }
+    writeInstallMarker(stamp);
+    log("kahin python paketi kuruldu/güncellendi");
   }
-  log("kahin python paketi kuruldu/güncellendi");
 
   if (process.env.KAHIN_SKIP_CAMOUFOX_FETCH) {
     log("Camoufox fetch atlandı (KAHIN_SKIP_CAMOUFOX_FETCH)");
     return { installed: true, camoufox: "skipped" };
   }
+  const readyCode = await run(
+    KAHIN_PY,
+    ["-c", "from pathlib import Path; from camoufox.pkgman import launch_path; raise SystemExit(0 if Path(launch_path()).exists() else 1)"],
+    15_000,
+  );
+  if (readyCode === 0) {
+    log("Camoufox browser zaten hazır; fetch atlandı");
+    return { installed: true, camoufox: "ready" };
+  }
   log("Camoufox browser hazırlanıyor (resmi camoufox fetch)...");
-  const browserCode = await run(KAHIN_PY, ["-m", "camoufox", "fetch"]);
+  const browserCode = await run(KAHIN_PY, ["-m", "camoufox", "fetch"], SETUP_COMMAND_TIMEOUT_MS);
   if (browserCode !== 0) {
     log(`Camoufox browser hazırlanamadı (çıkış ${browserCode}); kahin browser_start sırasında tekrar deneyecek`);
     return { installed: true, camoufox: "error", error: browserCode };
@@ -371,15 +421,28 @@ export async function installPython() {
   return { installed: true, camoufox: "ready" };
 }
 
-function run(cmd, args) {
+function run(cmd, args, timeoutMs = SETUP_COMMAND_TIMEOUT_MS) {
   return new Promise((resolve) => {
     const c = spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"] });
+    let timedOut = false;
+    let forceTimer;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      c.kill("SIGTERM");
+      forceTimer = setTimeout(() => c.kill("SIGKILL"), 5_000);
+    }, timeoutMs);
     c.on("error", (err) => {
+      clearTimeout(timer);
+      clearTimeout(forceTimer);
       process.stderr.write(`[kahin] ${cmd} başlatılamadı: ${err.message}\n`);
       resolve(1);
     });
     c.stderr.on("data", (d) => process.stderr.write(`[kahin] ${d}`));
-    c.on("close", (code) => resolve(code));
+    c.on("close", (code) => {
+      clearTimeout(timer);
+      clearTimeout(forceTimer);
+      resolve(timedOut ? 124 : code);
+    });
   });
 }
 

package/docs/juggler-ai-native.md

@@ -25,6 +25,11 @@ MCP tool
 - Aynı browser'ı ve aktif sekmeyi yeniden kullan. Başka sayfa gerektiğinde
   yeni browser açmak yerine `kahin_mirage_tab_new` ve
   `kahin_mirage_tab_switch` kullan.
+- `kahin_navigate` native response deadline'ına takılırsa mevcut target'ı
+  kapatıp aynı Mirage browser/context içinde bounded bir replacement target
+  açarak bir kez kurtarma yapabilir. Başarılı sonuçta `target_recovered: true`
+  gelir; browser PID'si değişmez. Bu durumda eski DOM `streamId`/nodeId'lerini
+  bırakıp yeni snapshot alın.
 - Juggler'da `Browser.*` browser köküne, `Page.*` ise aktif target/session'a
   aittir. MCP araçları session routing'i ajandan saklar.
 - `kahin_execute_cdp`, Mirage aktifken desteklenen CDP çağrılarını Juggler
@@ -63,9 +68,11 @@ Zorunlu kurallar:
 ## 3. Gerçek zamanlı DOM vericisi
 
 DOM stream sayfanın kendi `MutationObserver`'ını ve DOM event listener'larını
-kullanır. Sayfa tarafında bounded bir ring buffer tutulur; sidecar yalnızca
-değişiklik sinyali taşır. Böylece hızlı bir sayfa, sidecar reader'ını büyük
-DOM payload'ları ile bloke etmez.
+kullanır. Sayfa tarafında bounded bir ring buffer tutulur; mutation delta'ları
+layout/computed-style ölçümü yapmadan hafif kimlikler taşır, semantik/geometri
+ayrıntısı snapshot'tan alınır. Observer callback'i de bounded'dır; büyük bir
+belgenin parser/mutation kuyruğu sidecar reader'ını veya sonraki navigation'ı
+bloke etmez.
 
 ### 3.1 Tool sözleşmesi
 
@@ -146,6 +153,13 @@ Snapshot alanlarının anlamı:
 - `cursor`: o snapshot anındaki son sequence numarasıdır. Delta okumaya bu
   cursor'dan devam edilir.
 
+`dom_events` yanıtındaki `cursor`, gerçekten teslim edilen son event'in
+sequence numarasıdır; `limit` küçükse bekleyen event'leri atlamamak için bunu
+sonraki `after_seq` olarak kullanın. `nextSeq` ise sayfadaki canlı üst sınırdır
+ve henüz teslim edilmemiş event'leri de kapsayabilir. `kahin_agent_status`
+`domCursor` (son teslim edilen) ve `domNextSeq` (canlı üst sınır) alanlarını
+ayrı raporlar.
+
 ### 3.2 Delta ve event akışı
 
 ```json
@@ -166,7 +180,9 @@ Snapshot alanlarının anlamı:
       "added": [{"nodeId": "n8", "tag": "button", "role": "button", "name": "Save"}],
       "removed": [],
       "addedCount": 1,
-      "removedCount": 0
+      "addedTruncated": false,
+      "removedCount": 0,
+      "removedTruncated": false
     },
     {
       "seq": 7,
@@ -184,6 +200,10 @@ event'lerine ek olarak `input`, `change`, `focusin`, `focusout` ve `click`
 sayfa event'leri verilir. Bu event'ler neden-sonuç sinyalidir; tam güncel
 durum için snapshot yetkilidir.
 
+`added`/`removed` listeleri bounded'dır. `addedTruncated` veya
+`removedTruncated` true ise ilgili count listedeki node sayısından büyüktür;
+eksik node'ları tahmin etmeyin, yeni snapshot alın.
+
 `dom_events` için önerilen çağrı:
 
 ```json
@@ -217,7 +237,41 @@ mevcut `streamId`'yi karşılaştırır. `dom_start`'ten aldığınız `streamId
 her `dom_events` çağrısında geçirin; `stream_id` verilmezse navigation sessiz
 kalır ve eski cursor yeni document'ın event'leriyle karışabilir.
 
-### 3.4 Live action sözleşmesi
+### 3.5 Crawl challenge ve rate-limit sözleşmesi
+
+Her crawl döngüsünde `kahin_challenge_status` çağrısı yapılabilir. Araç Shadow
+ve Mirage'ın mevcut sayfasını, DOM, challenge widget selector'larını ve gerçek
+network response'larını
+birlikte gözlemler; 403/429/503 yanıtlarında `httpStatus` ve varsa
+`retryAfterSeconds` döndürür. `rate_limit` için `action` değeri
+`honor_retry_after_and_backoff`, CAPTCHA için ise
+`pause_for_human_or_authorized_provider` olur. Bu yüzey bypass/otomatik CAPTCHA
+çözümü yapmaz; ajan verilen karara uymalı ve aynı origin'i körlemesine tekrar
+çalıştırmamalıdır.
+
+### 3.6 Uzun süreli crawler job sözleşmesi
+
+Tek tek navigate çağrıları yerine uzun ve gözlenebilir bir crawl için şu ORBIT
+araçları kullanılır:
+
+- `kahin_crawl_start` — bounded seed/depth/page/time policy ile background job başlatır.
+- `kahin_crawl_status` — state, queue, sonuç, rotation, challenge ve engine health özetini döndürür.
+- `kahin_crawl_results` — opaque cursor ile en fazla 100 bounded sonucu döndürür.
+- `kahin_crawl_pause` / `kahin_crawl_resume` — CAPTCHA/access-denied sonrasında explicit insan/provider kararıyla devam eder.
+- `kahin_crawl_stop` — job'ı durdurur; browser'ı otomatik kapatmaz.
+
+Job varsayılan olarak aynı Mirage browser ve crawler tab'ını kullanır. 20 başarılı
+sayfa veya 900 saniyeden biri önce dolduğunda, tamamlanan sayfa ledger'a yazılır,
+engine aynı slotta yeniden başlatılır ve saved/inline identity config ile
+başlatılmış olsa bile effective Camoufox launch fingerprint'i yeniden üretilir;
+önceki hash ile aynıysa rotation reddedilir. Queue ve result cursor engine
+restart'tan etkilenmez.
+Rotation bir CAPTCHA veya rate-limit kaçış mekanizması değildir. 429/503 için
+Retry-After ve bounded exponential backoff uygulanır; CAPTCHA/access-denied
+durumunda job `paused` kalır ve `kahin_crawl_resume` çağrısı bekler. Resume
+challenge'ı çözmez, yeni origin'e kör retry yapmaz.
+
+### 3.7 Live action sözleşmesi
 
 İzin verilen action'lar: `click`, `hover`, `focus`, `type`, `scroll`, `select`.
 
@@ -283,7 +337,7 @@ script'i ayrıca evaluate eder. Observer sayfa tarafında bounded olduğu için
 
 ## 6. Juggler tool kataloğu (A-Z)
 
-Aşağıdaki liste Mirage'ın 107 Juggler-native tool'unun tamamıdır. `MIRAGE`
+Aşağıdaki liste Mirage'ın 104 Juggler-native tool'unun tamamıdır. `MIRAGE`
 tool'ları `engine="mirage"` aktifken kullanılır.
 
 ### DOM gözlem ve adaptif action (5)
@@ -312,6 +366,14 @@ tool'ları `engine="mirage"` aktifken kullanılır.
 - `kahin_mirage_wait_for_text`, `kahin_mirage_wait_for_timeout`
 - `kahin_mirage_route`
 
+`kahin_mirage_route` bir sonraki eşleşen isteği bekleyen bounded, tek-atımlık
+bir çağrıdır; navigate/click ile eşzamanlı çağrılır. `frame_id` verilirse yalnız
+o iframe'in isteğini eşleştirir. Seri MCP istemcileri önce
+`kahin_mirage_intercept_requests` çağırıp isteği
+`kahin_mirage_network_continue`/`kahin_mirage_network_abort` ile sürdürür ve
+ardından zorunlu olarak `kahin_mirage_unintercept_requests` çağırır; aksi halde
+gelecek istekler interception modunda bekleyebilir.
+
 ### Input (7)
 
 - `kahin_mirage_mouse_click`, `kahin_mirage_mouse_move`
@@ -324,6 +386,9 @@ tool'ları `engine="mirage"` aktifken kullanılır.
 - `kahin_mirage_reload`, `kahin_mirage_go_back`, `kahin_mirage_go_forward`
 - `kahin_mirage_stop`, `kahin_mirage_frame_tree`, `kahin_mirage_page_content`
 
+`kahin_mirage_page_content` HTML'i bounded döndürür; `htmlLength` gerçek
+belge boyutunu, `truncated` ise `html` alanının kesilip kesilmediğini bildirir.
+
 ### Tab/session (7)
 
 - `kahin_mirage_tab_new`, `kahin_mirage_tab_switch`, `kahin_mirage_tab_close`
@@ -364,6 +429,10 @@ tool'ları `engine="mirage"` aktifken kullanılır.
 - `kahin_mirage_set_file_chooser_intercept`
 - `kahin_mirage_upload_files`
 
+Upload çağrısı da `Page.fileChooserOpened` bekler. Input önceden tıklanmış
+olmalı veya `kahin_mirage_click(selector="input[type=file]")` ile eşzamanlı
+çağrılmalıdır; upload tool hangi input'u kendiliğinden seçmez.
+
 ### Screencast (4)
 
 - `kahin_mirage_screencast_start`, `kahin_mirage_screencast_frame`
@@ -384,6 +453,13 @@ en eski frame FIFO olarak döner.
   `last_error`); Mirage aktifse `prewarm` metadata'sı; engine yoksa
   yapılandırılmış `engine_unavailable` yanıtı (asla hata fırlatmaz)
 
+`kahin_mirage_accessibility_tree(max_nodes=N)` gerçek Camoufox AX ağacını
+alır, toplam `nodeCount`'ı raporlar ve ajana en fazla `N` node döndürür.
+Sidecar'ın raw AX cevabı da bounded'dır; büyük belgelerde beklenen sonuç
+`truncated: true` olabilir. `result_too_large` veya `truncated` gördüğünüzde
+engine'in öldüğünü varsaymayın; `kahin_engine_health` ile doğrulayın ve
+gerekirse DOM snapshot/selector ile hedef alanı daraltın.
+
 ### Agent-native (10)
 
 - `kahin_mirage_snapshot` — canlı DOM ağacını token bütçeli, ref'li satırlara
@@ -484,6 +560,7 @@ dom_events(after_seq=C, stream_id=S, frame_id=F, wait_ms=5000)
 | `reset`/`dropped` | Stream değişti veya ring overflow | Snapshot; eski cursor'u bırak |
 | `not_found` | Selector artık yok | Event/snapshot ile yeni hedef bul |
 | `truncated` | Snapshot cap'i küçük | Selector veya cap daralt/genişlet |
+| `cdp_command_failed` + `Page.navigate` response timeout | Native target navigation promise takıldı | Aynı browser içinde bounded target recovery yapılır; `target_recovered: true` ise yeni DOM snapshot al |
 | `unsupported_action` | Action allow-list dışında | Yalnızca desteklenen action kullan |
 | `not_text_input` | Hedef textbox değil | Role/name/action ipuçlarını tekrar değerlendir |
 | `not_select` | `action=select` hedefi `<select>` değil | Snapshot'taki action ipuçlarını tekrar değerlendir |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kahinmcp/kahin",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "Kahin \u2014 CDP ansiklopedisi + anti-detect browser otomasyon MCP sunucusu. Kurulumda 22 AI CLI arac\u0131n\u0131 otomatik tespit edip kendini kaydeder. Camoufox g\u00f6rsel varsay\u0131land\u0131r; Obscura h\u0131zl\u0131 CDP i\u015fleri i\u00e7in opt-in'dir.",
   "bin": {
     "kahin": "bin/kahin.mjs"
@@ -51,6 +51,6 @@
     "python"
   ],
   "dependencies": {
-    "@kahinmcp/kahin": "^0.3.8"
+    "@kahinmcp/kahin": "^0.3.9"
   }
 }