@kahinmcp/kahin 0.3.4 → 0.3.5

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.3.5] — 2026-08-06
+
+### Düzeltilen
+- `kahin_browser_start()` artık varsayılan olarak gerçek Camoufox/Mirage
+  başlatıyor; screenshot, mobile viewport, screencast, upload ve accessibility
+  çağrıları Shadow seçilmiş olsa bile Kahin içinde görsel backend'e yükseltiliyor.
+- Yeni capability sözleşmesi `kahin_engine_health` yanıtında motorun gerçek
+  görsel/mobile/DOM-stream/a11y/screencast sınırlarını raporluyor; generic
+  `kahin_screenshot` ve `Page.captureScreenshot` yolu dış otomasyon fallback'i
+  kullanmadan Camoufox'a geçiyor.
+- Shadow/Obscura artık bağımsız MCP/OpenCode süreçleri arasında sabit `9241`
+  portunu paylaşmıyor; varsayılan başlatma her child için geçici loopback portu
+  kullanıyor ve gerçek portu raporluyor.
+- Port çakışmasında ikinci child'ın yabancı browser WebSocket'ine bağlanıp
+  yanlışlıkla `started` dönmesi engellendi; child kararlılığı doğrulanmadan
+  engine state'e yayınlanmıyor ve başarısız child temizleniyor.
+- Mirage/Zig sidecar shutdown cancellation path'i child ve IPC kaynaklarını
+  güvenle temizliyor.
+
+### Testler
+- İki bağımsız Shadow instance'ı ve explicit port çakışması gerçek Obscura
+  binary'siyle regresyon testine alındı.
+- Shadow -> Camoufox screenshot handoff ve varsayılan motor gerçek browser ile
+  doğrulandı.
+- Python runtime suite: 115 passed; Zig sidecar tests/build: passed.
+
 ## [0.3.4] — 2026-08-05
 
 ### Eklenen
@@ -123,6 +149,7 @@ Tüm önemli değişiklikler bu dosyada tutulur. Format: [Keep a Changelog](http
 - CDP ansiklopedisi: 56 domain, 667 komut, 237 event, 609 type (Chrome 148)
 
 [0.3.4]: https://gitlab.com/void0x14/kahin-mcp/-/compare/v0.3.3...v0.3.4
+[0.3.5]: https://gitlab.com/void0x14/kahin-mcp/-/compare/v0.3.4...v0.3.5
 [0.3.3]: https://gitlab.com/void0x14/kahin-mcp/-/compare/v0.3.2...v0.3.3
 [0.3.2]: https://gitlab.com/void0x14/kahin-mcp/-/compare/v0.3.1...v0.3.2
 [0.2.0]: https://gitlab.com/void0x14/kahin-mcp/-/compare/v0.1.8...v0.2.0

package/README.md

@@ -87,7 +87,13 @@ Gerisini AI halleder. Ama dilersen tool'ları direkt de çağırabilirsin:
 → kahin_error_decode(error_code=-32601) → hatayı çözümler
 ```
 
-Camoufox (Juggler native) ile, engine `mirage` seçilince:
+`kahin_browser_start` varsayılan olarak Camoufox/Mirage başlatır. Shadow
+yalnızca hızlı, görsel olmayan CDP işleri için açıkça seçilir; screenshot,
+mobile viewport, screencast, upload veya accessibility isteyen bir tool,
+Shadow'ı Kahin içinde Camoufox'a yükseltir. Ajanın başka bir otomasyon
+kütüphanesine geçmesi gerekmez.
+
+Camoufox (Juggler native) ile:
 
 ```
 → kahin_browser_start(engine="mirage")
@@ -130,8 +136,13 @@ mcp · orjson · Levenshtein · websockets · httpx · camoufox · Pillow · pyd
 |------|-------|----------|
 | 9222 | Chrome DevTools | RESERVED |
 | 9240 | Kusatma Engine | RESERVED |
-| 9241 | Obscura (varsayılan) | Kahin kullanır |
-| 9242 | Mirage (varsayılan) | Kahin kullanır |
+| 9241 | Eski Shadow/Obscura sabit portu | Varsayılan olarak kullanılmaz |
+| — | Mirage/Camoufox | TCP portu yok; Juggler stdio pipe kullanır |
+
+Shadow/Obscura için `kahin_browser_start` port verilmeden çağrıldığında Kahin,
+her child için loopback üzerinde kernel'den geçici bir port alır. Böylece aynı
+makinedeki bağımsız MCP/OpenCode süreçleri birbirlerinin WebSocket'ine bağlanmaz.
+Sabit port yalnızca özellikle `port=...` verildiğinde kullanılır.
 
 ## Kendi Kendini Onarma
 
@@ -146,7 +157,8 @@ Kahin'de hata loglama ve kendini onarma sistemi gömülüdür:
 ```
 oracle.py               → MCP server (bootstrap: mcp instance + engine lifecycle + main)
   tools/                → 109 tool, engine-ayrımlı kategori dosyaları
-    _common.py          → _safe_cdp, _require_engine, _auto_learn
+    _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)
     pilot/trainman/dejavu           → browser/session/debug (paylaşılan)
     pilot_mirage/trainman_mirage/dejavu_mirage → Camoufox DOM+Input+PageEx / Tab / Network+Console
@@ -167,7 +179,7 @@ camoufox-harness/       → Zig sidecar (Juggler protocol, vendor binary gömül
 ## 🗺️ Yol Haritası
 
 - [x] **Juggler protokolü** için AI-native uçtan uca dokümantasyon, kullanım ve pratik örnekleri
-- [x] **Camoufox entegrasyonu tamamlandı** — gerçek Camoufox (Zig sidecar + Juggler pipe) ile native çalışıyor; engine seçimi ajan tarafından `shadow`/`mirage` parametresiyle yapılıyor
+- [x] **Camoufox entegrasyonu tamamlandı** — gerçek Camoufox (Zig sidecar + Juggler pipe) varsayılandır; görsel capability isteyen Shadow çağrıları Kahin içinde Mirage'a yükseltilir
 - [x] **Obscura entegrasyonu tamamlandı** — gerçek Obscura binary'si (WebSocket CDP) ile çalışıyor, startup problemleri giderildi
 - [ ] **SKILLS** destekleri ve konfigre edilebilir kişsiel hazır skills oluşturma özelliği
 - [x] **Tek tık kurulum** — `pnpm add -g @kahinmcp/kahin`, sonra `kahin` (ilk çalıştırmada Python ortamını otomatik kurar)

package/bin/setup.mjs

@@ -324,7 +324,7 @@ 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.4-py3-none-any.whl");
+const KAHIN_WHEEL = join(dirname(fileURLToPath(import.meta.url)), "..", "lib", "kahin-0.3.5-py3-none-any.whl");
 
 // Gömülü wheel'i venv'e kurar. Postinstall'da ve `kahin setup`'ta çalışır.
 // PyPI'a bağımlı DEĞİL — wheel paketle birlikte gelir.

package/docs/juggler-ai-native.md

@@ -14,7 +14,13 @@ MCP tool
       -> Camoufox Page/Browser
 ```
 
-- `engine="mirage"` bir Camoufox süreci ve tek bir sidecar başlatır.
+- `kahin_browser_start` varsayılan olarak bir Camoufox süreci ve tek bir
+  sidecar başlatır. `engine="shadow"` yalnızca hızlı, görsel olmayan CDP
+  işleri için açıkça seçilir.
+- Shadow aktifken screenshot, mobile emulation, accessibility, upload veya
+  screencast isteyen bir tool çağrısı, aktif URL'i koruyarak Kahin içinde
+  Shadow -> Mirage yükseltmesi yapar. Ajanın Playwright ya da başka bir
+  otomasyon kütüphanesine geçmesi sözleşme dışıdır.
 - İlk sayfa ilk sayfa tool'u çağrıldığında tembel olarak oluşturulur.
 - Aynı browser'ı ve aktif sekmeyi yeniden kullan. Başka sayfa gerektiğinde
   yeni browser açmak yerine `kahin_mirage_tab_new` ve
@@ -22,8 +28,9 @@ MCP tool
 - 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
-  eşdeğerine yönlendirir; Juggler'da bulunmayan her CDP domain'i varmış gibi
-  tahmin etme.
+  eşdeğerine yönlendirir; görsel capability isteyen bilinen çağrılar Shadow
+  aktifse önce Mirage'a yükseltilir. Juggler'da bulunmayan her CDP domain'i
+  varmış gibi tahmin etme.
 
 ## 2. Ajanın temel protokolü
 
@@ -346,6 +353,12 @@ tool'ları `engine="mirage"` aktifken kullanılır.
 - `kahin_mirage_screencast_start`, `kahin_mirage_screencast_frame`
 - `kahin_mirage_screencast_stop`, `kahin_mirage_screencast_pending`
 
+`kahin_mirage_screencast_frame(fresh=true)`, önceki çağrıların ACK edilmiş
+ama henüz kuyrukta kalan frame'lerini temizler ve çağrıdan sonra gelen ilk
+frame'i bekler. Sayfa mutation'ı veya viewport değişiminden sonra görsel
+doğrulama için bu yol kullanılmalıdır; varsayılan `fresh=false` ise kuyruktaki
+en eski frame FIFO olarak döner.
+
 ### Accessibility ve health (2)
 
 - `kahin_mirage_accessibility_tree`
@@ -391,7 +404,7 @@ dom_events(after_seq=C, stream_id=S, frame_id=F, wait_ms=5000)
 
 | Hata/sinyal | Sebep | Kurtarma |
 |---|---|---|
-| `Browser engine is not running` | Start yok | `kahin_browser_start(engine="mirage")` |
+| `Browser engine is not running` | Start yok | `kahin_browser_start()` |
 | `Browser engine is dead` | Sidecar/Camoufox öldü | `kahin_browser_stop`, sonra yeni `start` |
 | `stale_node` | Node silindi veya document değişti | Snapshot + yeni nodeId |
 | `reset`/`dropped` | Stream değişti veya ring overflow | Snapshot; eski cursor'u bırak |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kahinmcp/kahin",
-  "version": "0.3.4",
-  "description": "Kahin — CDP ansiklopedisi + anti-detect browser otomasyon MCP sunucusu. Kurulumda 22 AI CLI aracını otomatik tespit edip kendini kaydeder. Obscura ve Camoufox motorlarını kullanır, motor seçimini ajana bırakır.",
+  "version": "0.3.5",
+  "description": "Kahin — CDP ansiklopedisi + anti-detect browser otomasyon MCP sunucusu. Kurulumda 22 AI CLI aracını otomatik tespit edip kendini kaydeder. Camoufox görsel varsayılandır; Obscura hızlı CDP işleri için opt-in'dir.",
   "bin": {
     "kahin": "bin/kahin.mjs"
   },