Merge pull request #32 from diegosouzapw/fix/port-issue-102-warm-session-gate

fix(proxy): stop mid-session enables from re-paying the whole cached prefix

Author: diegosouzapw

CHANGELOG.md

@@ -93,6 +93,17 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · semantic ver
 
 ### Fixed
 
+- **fix(proxy):** enabling the proxy mid-session no longer "instant drains" the
+  caller's budget. A session that ran without OmniGlyph holds its whole prefix
+  cached by Anthropic as text at the 0.1× read rate; the first imaged request
+  re-paid all of it as a fresh 1.25× cache write in one prompt. The
+  profitability gate already modeled that burn (`priorWarmTokens × (CC − CR)`)
+  but nothing fed it in production. The proxy now estimates the warm text
+  prefix (chars up to the caller's last `cache_control` marker) for any session
+  it has never imaged and passes it to the gate, so the flip only happens when
+  imaging still wins; sessions OmniGlyph already images keep compressing with
+  no penalty. New FAQ entry (README + the 41 translations) explains the
+  mid-session behavior. (thanks @Idle0dreamer)
 - **fix(transform):** preserve the exact Claude Code OAuth identity ("You are
   Claude Code, Anthropic's official CLI for Claude.") as the first, separate
   top-level system text block. Subscription OAuth traffic is classified as

README.md

@@ -234,6 +234,9 @@ OmniGlyph-export-<hash>/
 
 # 🧠 FAQ
 
+**I enabled it mid-session and my usage spiked — why?**
+A session that ran without OmniGlyph has its entire prefix cached by Anthropic as text at the 0.1× read rate; the first imaged request would re-pay all of it as a fresh 1.25× cache write in a single prompt. The proxy guards against this: a session it has never imaged feeds that one-prompt cost into the break-even gate and only switches to images when it still wins — otherwise the session stays as text, and the savings start with your next new session.
+
 **Is the 59–70% end-to-end, or only on the requests it touched?**
 End-to-end — the whole bill. Most compression tools report savings only on the slice they touched, which flatters the number. Our denominator is *every* request: the small ones the gate correctly left untouched, all cache writes and reads, and all output tokens (which the proxy never compresses). Compressed-only runs higher and is quoted separately, never as the headline.
 

docs/i18n/ar/README.md

@@ -175,6 +175,9 @@ OmniGlyph-export-<hash>/
 
 # 🧠 الأسئلة الشائعة
 
+**فعّلته في منتصف الجلسة فقفز الاستهلاك — لماذا؟**
+الجلسة التي عملت بدون OmniGlyph تكون بادئتها كاملةً مخزّنة مؤقتًا لدى Anthropic كنص بمعدل قراءة 0.1×؛ وأول طلب بالصور سيعيد دفع كل ذلك ككتابة تخزين مؤقت جديدة بمعدل 1.25× في موجّه واحد. يحمي الوكيل من ذلك: الجلسة التي لم يحوّلها قط إلى صور تُدخل هذه التكلفة لمرة واحدة في بوابة نقطة التعادل، ولا يتحول إلى الصور إلا إذا ظل ذلك مجديًا — وإلا تبقى الجلسة نصًا ويبدأ التوفير مع جلستك الجديدة التالية.
+
 **هل نسبة 59–70% من طرف إلى طرف، أم فقط على الطلبات التي لمستها؟**
 من طرف إلى طرف — الفاتورة بأكملها. معظم أدوات الضغط تُبلغ عن الوفورات فقط على الشريحة التي لمستها، ما يُجمّل الرقم. المقام لدينا هو *كل* طلب: الطلبات الصغيرة التي تركتها البوّابة بحق دون تحويل، وكل كتابات وقراءات التخزين المؤقت (cache)، وكل رموز المخرجات (التي لا يضغطها البروكسي أبدًا). التشغيل بضغط فقط يُعطي رقمًا أعلى ويُذكر بشكل منفصل، لا كعنوان رئيسي أبدًا.
 

docs/i18n/az/README.md

@@ -175,6 +175,9 @@ OmniGlyph-export-<hash>/
 
 # 🧠 Tez-tez verilən suallar
 
+**Sessiyanın ortasında aktivləşdirdim və istifadə sıçradı — niyə?**
+OmniGlyph olmadan işləyən sessiyanın bütün prefiksi Anthropic-də mətn kimi 0,1× oxuma tarifi ilə keşlənib; şəkilli ilk sorğu bunların hamısını tək bir promptda 1,25× ilə yeni keş yazısı kimi yenidən ödətdirərdi. Proksi bundan qoruyur: heç vaxt şəkilə çevirmədiyi sessiyanın bu birdəfəlik xərcini zərərsizlik qapısına daxil edir və yalnız hələ də sərfəli olduqda şəkillərə keçir — əks halda sessiya mətn olaraq qalır və qənaət növbəti yeni sessiyanızdan başlayır.
+
 **59–70% uçdan-uca rəqəmdir, yoxsa yalnız toxunduğu sorğularda?**
 Uçdan-uca — bütün hesab. Əksər sıxılma alətləri qənaəti yalnız toxunduqları hissədə bildirir, bu da rəqəmi şişirdir. Bizim məxrəcimiz *hər* sorğudur: qapının düzgün toxunmadan buraxdığı kiçik sorğular, bütün keş yazma və oxumaları, və bütün çıxış tokenləri (proksi bunları heç vaxt sıxmır). Yalnız-sıxılmış rəqəm daha yüksək çıxır və ayrıca qeyd olunur, heç vaxt başlıq kimi yox.
 

docs/i18n/bg/README.md

@@ -175,6 +175,9 @@ OmniGlyph-export-<hash>/
 
 # 🧠 Често задавани въпроси
 
+**Включих го по средата на сесия и разходът скочи — защо?**
+Сесия, работила без OmniGlyph, има целия си префикс кеширан от Anthropic като текст при четяща ставка 0,1×; първата заявка с изображения би платила всичко това отново като нов запис в кеша при 1,25× в един-единствен промпт. Проксито пази от това: сесия, която никога не е превръщало в изображения, включва този еднократен разход в гейта за рентабилност и преминава към изображения само ако все още си струва — иначе сесията остава текст, а спестяванията започват със следващата нова сесия.
+
 **59–70% от край до край ли е, или само за заявките, които са били засегнати?**
 От край до край — цялата сметка. Повечето инструменти за компресия отчитат спестявания само за частта, която са засегнали, което разкрасява числото. Нашият знаменател е *всяка* заявка: малките, които вратата правилно е оставила недокоснати, всички записи и четения от кеша, и всички изходни токени (които проксито никога не компресира). Стойността само за компресираните заявки е по-висока и се посочва отделно, никога като главно число.
 

docs/i18n/bn/README.md

@@ -175,6 +175,9 @@ OmniGlyph-export-<hash>/
 
 # 🧠 প্রায়শই জিজ্ঞাসিত প্রশ্ন
 
+**সেশনের মাঝপথে চালু করলাম আর খরচ লাফিয়ে বাড়ল — কেন?**
+OmniGlyph ছাড়া চলা সেশনের পুরো প্রিফিক্স Anthropic-এ টেক্সট হিসেবে 0.1× রিড রেটে ক্যাশ থাকে; ছবিসহ প্রথম অনুরোধটি এক প্রম্পটেই সেই সবকিছু 1.25× হারে নতুন ক্যাশ-রাইট হিসেবে আবার পরিশোধ করাত। প্রক্সি এর থেকে রক্ষা করে: যে সেশনকে সে কখনো ছবিতে রূপান্তর করেনি, তার এই এককালীন খরচ ব্রেক-ইভেন গেটে যোগ হয় এবং কেবল তখনই ছবিতে যায় যখন এখনো লাভজনক — নাহলে সেশন টেক্সটই থাকে, আর সাশ্রয় শুরু হয় আপনার পরের নতুন সেশন থেকে।
+
 **59–70% কি এন্ড-টু-এন্ড, নাকি শুধু যেসব রিকোয়েস্ট এটি স্পর্শ করেছে তার ওপর?**
 এন্ড-টু-এন্ড — পুরো বিল। বেশিরভাগ কম্প্রেশন টুল শুধু তারা যে অংশ স্পর্শ করেছে তার ওপর সাশ্রয় রিপোর্ট করে, যা সংখ্যাটিকে ফুলিয়ে দেখায়। আমাদের ডিনোমিনেটর হলো *প্রতিটি* রিকোয়েস্ট: ছোট রিকোয়েস্টগুলো যেগুলো গেট সঠিকভাবে অস্পৃষ্ট রেখেছে, সব ক্যাশ রাইট ও রিড, এবং সব আউটপুট টোকেন (যা প্রক্সি কখনো কম্প্রেস করে না)। শুধু-কম্প্রেসড হিসাব বেশি দেখায় এবং তা আলাদাভাবে উল্লেখ করা হয়, কখনো হেডলাইন হিসেবে নয়।
 

docs/i18n/cs/README.md

@@ -175,6 +175,9 @@ OmniGlyph-export-<hash>/
 
 # 🧠 Časté dotazy
 
+**Zapnul jsem to uprostřed sezení a spotřeba vyletěla — proč?**
+Sezení běžící bez OmniGlyph má celý prefix uložený u Anthropic v cache jako text za čtecí sazbu 0,1×; první požadavek s obrázky by to vše znovu zaplatil jako nový zápis do cache za 1,25× v jediném promptu. Proxy před tím chrání: sezení, které nikdy nepřevedla na obrázky, započítá tento jednorázový náklad do break-even brány a na obrázky přepne, jen pokud se to stále vyplatí — jinak sezení zůstává textem a úspory začínají příštím novým sezením.
+
 **Je těch 59–70 % z konce do konce, nebo jen na requestech, kterých se to týkalo?**
 Z konce do konce — celý účet. Většina kompresních nástrojů reportuje úspory jen na části, které se dotkly, což číslo přikrášlí. Náš jmenovatel je *každý* request: malé, které gate správně nechal netknuté, všechny zápisy a čtení cache a všechny výstupní tokeny (které proxy nikdy nekomprimuje). Číslo jen za komprimované requesty vychází vyšší a uvádí se odděleně, nikdy jako hlavní tvrzení.
 

docs/i18n/da/README.md

@@ -175,6 +175,9 @@ OmniGlyph-export-<hash>/
 
 # 🧠 FAQ
 
+**Jeg slog det til midt i en session, og forbruget røg i vejret — hvorfor?**
+En session, der kørte uden OmniGlyph, har hele sit præfiks cachet hos Anthropic som tekst til 0,1× læsetakst; den første forespørgsel med billeder ville genbetale det hele som en frisk cache-skrivning til 1,25× i én enkelt prompt. Proxyen beskytter mod dette: en session, den aldrig har billedliggjort, får denne engangsomkostning regnet ind i break-even-porten og skifter kun til billeder, hvis det stadig kan betale sig — ellers forbliver sessionen tekst, og besparelsen begynder med din næste nye session.
+
 **Er de 59–70 % end-to-end, eller kun på de forespørgsler, den rørte ved?**
 End-to-end — hele regningen. De fleste komprimeringsværktøjer rapporterer kun besparelser på den del, de rørte ved, hvilket smigrer tallet. Vores nævner er *hver eneste* forespørgsel: de små, som spærringen med rette lod være urørt, alle cache-skrivninger og -læsninger, og alle output-tokens (som proxyen aldrig komprimerer). Kun-komprimeret-tallet er højere og angives separat, aldrig som hovedtal.
 

docs/i18n/de/README.md

@@ -175,6 +175,9 @@ OmniGlyph-export-<hash>/
 
 # 🧠 FAQ
 
+**Ich habe es mitten in einer Session aktiviert und mein Verbrauch schoss hoch — warum?**
+Eine Session, die ohne OmniGlyph lief, hat ihren gesamten Präfix bei Anthropic als Text zum 0,1×-Leseraten-Tarif im Cache; die erste Bild-Anfrage würde all das als neuen Cache-Write zu 1,25× in einem einzigen Prompt erneut bezahlen. Der Proxy schützt davor: Eine Session, die er nie in Bilder umgewandelt hat, speist diese Einmalkosten in das Break-even-Gate ein und wechselt nur zu Bildern, wenn es sich weiterhin lohnt — andernfalls bleibt die Session Text, und die Ersparnis beginnt mit der nächsten neuen Session.
+
 **Ist die Ersparnis von 59–70 % Ende-zu-Ende, oder nur bei den Requests, die tatsächlich konvertiert wurden?**
 Ende-zu-Ende — die gesamte Rechnung. Die meisten Kompressionstools geben Einsparungen nur für den Teil an, den sie tatsächlich bearbeitet haben, was die Zahl schönt. Unser Nenner ist *jeder* Request: die kleinen, die das Gate zu Recht unangetastet ließ, alle Cache-Writes und -Reads, sowie alle Output-Tokens (die der Proxy nie komprimiert). Nur die konvertierten Requests liegen höher und werden separat angegeben, nie als Schlagzeile.
 

docs/i18n/es/README.md

@@ -175,6 +175,9 @@ OmniGlyph-export-<hash>/
 
 # 🧠 FAQ
 
+**Lo activé a mitad de una sesión y mi consumo se disparó, ¿por qué?**
+Una sesión que corrió sin OmniGlyph tiene todo su prefijo cacheado por Anthropic como texto a la tarifa de lectura de 0,1×; la primera petición con imágenes volvería a pagar todo eso como una escritura de caché nueva a 1,25× en un solo prompt. El proxy protege contra esto: una sesión que nunca ha convertido a imágenes alimenta ese coste único al gate de break-even y solo cambia a imágenes cuando aún compensa — de lo contrario la sesión sigue como texto y el ahorro empieza con tu próxima sesión nueva.
+
 **¿El 59–70% es de punta a punta, o solo en los requests que tocó?**
 De punta a punta — la factura completa. La mayoría de las herramientas de compresión reportan ahorros solo sobre la porción que tocaron, lo que favorece el número. Nuestro denominador es *cada* request: los pequeños que el gate correctamente dejó intactos, todas las escrituras y lecturas de cache, y todos los tokens de salida (que el proxy nunca comprime). El ahorro solo-comprimido da un número más alto y se cita por separado, nunca como titular.