@operatingtag/dsh-unclesam 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,261 @@
-# Temporary Holding Version
+**English** · [Español](README.es.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Português](README.pt.md) · [Italiano](README.it.md) · [Türkçe](README.tr.md) · [한국어](README.ko.md) · [日本語](README.ja.md) · [简体中文](README.zh.md) · [Русский](README.ru.md) · [Polski](README.pl.md) · [हिन्दी](README.hi.md) · [Nederlands](README.nl.md) · [Українська](README.uk.md) · [Tiếng Việt](README.vi.md) · [Bahasa Indonesia](README.id.md)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Uncle Sam
+
+**A DeepSeek Harness provider that answers through your own browser, on your existing web account, instead of the billed API.**
+
+**☕ [Buy me a coffee](https://revolut.me/operatingtag)** — written by one person, at night, funded by nothing. There is no other revenue model. A star or a bug report is worth just as much.
+
+> **This product is ongoing and under active development. Expect bugs.**
+>
+> It works, it is fast, and it has been driven daily for weeks — but it keeps changing, and the browser route
+> depends on a website that changes without telling anyone. If something breaks, a screenshot and the version
+> number is worth more than a description. Pin a version if you depend on it.
+
+```
+provider   deepseek-web
+models     deepseek-chat · deepseek-chat-search · deepseek-reasoner · deepseek-reasoner-search
+cost       nothing per token — it uses the subscription already open in your browser
+status     ongoing development — expect bugs
+measured   first token ~1.9 s · overhead ~0.6 s · a full turn in ~2.5 s
+```
+
+Replies from the web route are signed **🔴 Uncle Sam**. That name is a joke, not a claim: it marks which route
+answered, and API replies carry no signature at all. You always know which of the two answered you.
+
+---
+
+## What it saves you
+
+The API bills per token. The web product does not. This plugin registers `deepseek-web` as a model provider and
+answers every call by driving `chat.deepseek.com` in a real browser — the page does the work, the browser holds
+the session, and nothing is metered.
+
+| | API route | Web route |
+|---|---|---|
+| Cost | per token, forever | nothing beyond the subscription |
+| Speed | fast | ~2.5 s a turn, measured |
+| Tool calling | native and reliable | emulated, works but weaker |
+| Depends on | the API | a website that changes without notice |
+
+**Both routes stay installed.** The model picker is the switch, so you can use the cheap one by default and
+reach for the API when a task needs reliable tool use.
+
+---
+
+## Installing
+
+Uncle Sam is a **DeepSeek Harness plugin**. It does nothing outside the harness, because it registers a model
+provider, a host route and two client UI slots.
+
+**Requirements**
+
+| | |
+|---|---|
+| DeepSeek Harness | any recent build with the plugin manager |
+| Browser | Brave recommended, Edge used automatically when Brave is absent |
+| Node | 22 or newer |
+
+**From npm**
+
+```bash
+pnpm add @operatingtag/dsh-unclesam
+```
+
+**From this repository**
+
+```bash
+git clone https://github.com/operatingtag/dsh-unclesam
+cd dsh-unclesam
+pnpm install
+```
+
+Then add the bundle row to your profile so the harness loads it:
+
+```yaml
+# cordis.patch.yml
+- insert:
+    - id: dsh-unclesam
+      name: '@operatingtag/dsh-unclesam'
+      config:
+        port: 9222
+        defaultModel: deepseek-chat-search
+        autoMinimise: true
+```
+
+**Or from a folder:** Settings → Plugins → install from a local path, pointed at the folder holding
+`package.json`.
+
+### First run
+
+Click **Sign in / open chat**. The browser opens and **stays visible** until you have signed in at
+chat.deepseek.com. After that it minimises itself and you will not see it again. The session lives in your
+browser profile, so **no password is stored by the plugin** — there is nothing to leak.
+
+You should then see:
+
+1. **Settings → Uncle Sam** — a page with status rows and a sign-in button.
+2. **Under the chat box** — `● DeepSeek Harness` or `● Uncle Sam`, click to switch.
+3. **The model list** — four `(web)` models beside the API models.
+
+### Removing it
+
+Settings → Plugins → Uncle Sam → Uninstall. Nothing is written outside the browser profile you signed in to.
+
+---
+
+## The API / web switch
+
+**The model picker is the switch.** There is no second control, because a second control that also chose the
+model would be two sources of truth for one decision.
+
+| Pick this model | Route | DeepThink | Search |
+|---|---|---|---|
+| `DeepSeek Chat (web)` | browser | off | off |
+| `DeepSeek Chat + Search (web)` | browser | off | **on** |
+| `DeepSeek Reasoner (web)` | browser | **on** | off |
+| `DeepSeek Reasoner + Search (web)` | browser | **on** | **on** |
+| any model without `(web)` | the API | — | — |
+
+A **WEB** or **API** badge renders beside the model label so the active route is visible at a glance. When the
+label is not recognised the badge renders nothing rather than guessing — a wrong badge is worse than none.
+
+Your choice persists across restarts. **DeepThink** is the reasoning pass; **Search** lets it read the live web.
+
+### Search is visible in the transcript
+
+With a search model, a turn produces **two blocks** — the query it searched with, the sources it found, then
+the answer that used them:
+
+```
+Web search — "What is one technology news headline from today?"
+Sources (4): yna.co.kr · fnnews.com · rthk.hk · sina.com.cn
+Links: https://k.sina.com.cn/article_... http://www.21jingji.com/article_...
+```
+
+The page does not expose the query it typed internally, so the quoted query is the prompt that triggered the
+search. Sources and links are read from the page once the answer settles. Because sources only exist at the
+end, **search turns buffer instead of streaming**; ordinary turns still stream token by token.
+
+---
+
+## Why a browser, and not their HTTP API
+
+The obvious route — calling `chat.deepseek.com`'s own API — was attempted and abandoned. The site makes every
+message clear two gates:
+
+| Gate | What it means |
+|---|---|
+| `/api/v0/chat/create_pow_challenge` | a **proof-of-work** challenge per message |
+| `challenges.cloudflare.com/turnstile` | a bot gate on the origin |
+
+Re-implementing either is a losing game: they are obfuscated, they change, and when they change the failure
+looks exactly like a network fault. **The page already solves both for its own requests.**
+
+So the adapter never speaks HTTP to the site. It drives the page, and the page does the rest. Auth,
+proof-of-work and Turnstile stop being our problem and cannot break independently of the site itself.
+
+**Verified:** a plain `HEAD` to the site returns `403`; the browser path returns answers.
+
+---
+
+## Limits, stated honestly
+
+**Tool use is emulated.** A web chat has no structured tool channel, so tools are described in the prompt and
+a call is recovered by parsing a JSON object out of the reply. It works — verified — but it is weaker than
+native tool calling: a model that ignores the instruction answers in prose, and the harness sees no tool use
+that turn. **For heavy agentic work the API route is more reliable.** The web route is best for chat, long
+answers, subagents, compaction, and any turn where the model must be the web model.
+
+**It depends on a website you do not control.** When the page changes shape, the plugin has to change with it.
+That is the ongoing-development warning at the top of this page, not a formality.
+
+**It is not affiliated with DeepSeek.** It is not endorsed by them, and it gives you no rights in their
+service. Your use of that service is governed by their terms.
+
+---
+
+## Configuration
+
+`cordis.patch.yml` sets:
+
+| key | default | meaning |
+|---|---|---|
+| `port` | `9222` | the browser's debugging port |
+| `defaultModel` | `deepseek-chat-search` | used when a call names no model |
+| `showBrowser` | `true` | whether the window is visible while it works |
+
+The browser must hold a signed-in `chat.deepseek.com` session. The first call launches Brave on the **Default**
+profile if the port is not already open. If Brave is already running *without* a debugging port, the adapter
+cannot attach, and says so clearly rather than failing silently.
+
+---
+
+## Architecture
+
+```
+index.js          the adapter: harness StreamChunk  ←→  engine
+lib/engine.mjs    browser + page: type, send, stream, settle
+lib/cdp.mjs       Chrome DevTools Protocol client, zero dependencies
+lib/prompt.mjs    flatten messages + tools into one message; recover tool calls from the reply
+lib/savings.mjs   what the web route saved you, priced against the API
+lib/i18n.mjs      51 languages for the panel
+```
+
+**No dependencies.** Node 24 ships a global `WebSocket` and `fetch`, which is all CDP needs, so the token
+stream never leaves the host process and there is no IPC hop per delta.
+
+---
+
+## Support
+
+Uncle Sam exists so you stop paying per token. If it saved you money, and you would like to see the next one
+built on hardware that does not run out of memory halfway through:
+
+**[☕ revolut.me/operatingtag](https://revolut.me/operatingtag)**
+
+A star on the repo or a useful bug report is worth just as much.
+
+---
+
+## Licence
+
+**CC BY-NC-ND 4.0** — Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International.
+Copyright (c) 2026 Darren T. Weldon, published under the Operating Tag name.
+
+**The whole deal, in one line: install it and use it, personally, for free. Do not change it, do not share
+it, do not sell it, and do not use it in a business.**
+
+That is not open source, and it does not pretend to be.
+
+```
+you may      install it and run it · use it personally, non-commercially
+             read the source to understand it
+
+you may not  modify, adapt or create a derivative of it
+             copy, distribute, publish, mirror or make it available to anyone
+             upload it to any code host, registry, website, forum or chat
+             sell, resell, rent, or charge for it or for access to it
+             bundle it into anything you supply to another person
+             use it for any commercial purpose, or in the course of a business
+```
+
+**The only two legitimate sources are this repository and the npm package
+[`@operatingtag/dsh-unclesam`](https://www.npmjs.com/package/@operatingtag/dsh-unclesam).** A copy from
+anywhere else is not licensed, whoever supplied it. If you see this software for sale, it is not being sold by
+its author.
+
+**Commercial use, and the right to modify and distribute, are available under a separate written licence.**
+Ask Operating Tag and you will get a straight answer and a clear price.
+
+The [LICENSE](LICENSE) file governs, and it opens with the same summary in plain English.
+
+---
+
+Uncle Sam is an independent plugin. Not affiliated with, endorsed by, or supported by DeepSeek.
+
+```
+@operatingtag/dsh-unclesam   v1.0.1
+Author   Operating Tag
+Licence  CC BY-NC-ND 4.0 — free to use, not to change, share or sell
+```

package/README.nl.md

@@ -0,0 +1,266 @@
+[English](README.md) · [Español](README.es.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Português](README.pt.md) · [Italiano](README.it.md) · [Türkçe](README.tr.md) · [한국어](README.ko.md) · [日本語](README.ja.md) · [简体中文](README.zh.md) · [Русский](README.ru.md) · [Polski](README.pl.md) · [हिन्दी](README.hi.md) · **Nederlands** · [Українська](README.uk.md) · [Tiếng Việt](README.vi.md) · [Bahasa Indonesia](README.id.md)
+
+# Uncle Sam
+
+**Een provider voor DeepSeek Harness die antwoordt via je eigen browser, op het webaccount dat je al hebt, in plaats van via de betaalde API.**
+
+**☕ [Trakteer me op een koffie](https://revolut.me/operatingtag)** — geschreven door één persoon, 's nachts, zonder financiering. Er is geen ander verdienmodel. Een ster of een bruikbare bugmelding is net zoveel waard.
+
+> **Dit product is volop in ontwikkeling. Verwacht bugs.**
+>
+> Het werkt, het is snel en het draait al weken dagelijks — maar het verandert voortdurend, en de browserroute
+> hangt af van een website die zonder waarschuwing verandert. Als er iets stukgaat, zijn een schermafbeelding en
+> het versienummer meer waard dan een beschrijving. Pin een versie als je ervan afhankelijk bent.
+
+```
+provider   deepseek-web
+modellen   deepseek-chat · deepseek-chat-search · deepseek-reasoner · deepseek-reasoner-search
+kosten     niets per token — gebruikt het abonnement dat al in je browser openstaat
+status     in ontwikkeling — verwacht bugs
+gemeten    eerste token ~1,9 s · overhead ~0,6 s · een hele beurt in ~2,5 s
+```
+
+Antwoorden via de webroute zijn ondertekend met **🔴 Uncle Sam**. Die naam is een grap, geen claim: hij markeert
+welke route antwoordde, en API-antwoorden hebben helemaal geen ondertekening. Je weet altijd wie je antwoord gaf.
+
+---
+
+## Wat het je bespaart
+
+De API rekent per token. Het webproduct niet. Deze plugin registreert `deepseek-web` als modelprovider en
+beantwoordt elke aanroep door `chat.deepseek.com` in een echte browser te besturen — de pagina doet het werk, de
+browser houdt de sessie vast, en er wordt niets gemeten.
+
+| | API-route | Webroute |
+|---|---|---|
+| Kosten | per token, altijd | niets bovenop het abonnement |
+| Snelheid | snel | ~2,5 s per beurt, gemeten |
+| Tool-aanroepen | native en betrouwbaar | nagebootst, werkt maar zwakker |
+| Hangt af van | de API | een website die zonder waarschuwing verandert |
+
+**Beide routes blijven geïnstalleerd.** De modelkiezer is de schakelaar: gebruik standaard de goedkope route en
+grijp naar de API wanneer een taak betrouwbare tools nodig heeft.
+
+---
+
+## Installeren
+
+Uncle Sam is een **DeepSeek Harness-plugin**. Buiten de harness doet hij niets, omdat hij een modelprovider, een
+hostroute en twee UI-plekken registreert.
+
+**Vereisten**
+
+| | |
+|---|---|
+| DeepSeek Harness | elke recente build met pluginbeheer |
+| Browser | Brave aanbevolen, Edge wordt automatisch gebruikt als Brave ontbreekt |
+| Node | 22 of nieuwer |
+
+**Vanaf npm**
+
+```bash
+pnpm add @operatingtag/dsh-unclesam
+```
+
+**Vanuit deze repository**
+
+```bash
+git clone https://github.com/operatingtag/dsh-unclesam
+cd dsh-unclesam
+pnpm install
+```
+
+Voeg dan de pakketregel toe aan je profiel zodat de harness hem laadt:
+
+```yaml
+# cordis.patch.yml
+- insert:
+    - id: dsh-unclesam
+      name: '@operatingtag/dsh-unclesam'
+      config:
+        port: 9222
+        defaultModel: deepseek-chat-search
+        autoMinimise: true
+```
+
+**Of vanuit een map:** Instellingen → Plugins → installeren vanaf een lokaal pad, wijzend naar de map met
+`package.json`.
+
+### Eerste keer
+
+Klik op **Inloggen / chat openen**. De browser opent en **blijft zichtbaar** tot je bent ingelogd op
+chat.deepseek.com. Daarna minimaliseert hij zichzelf en zie je hem niet meer. De sessie leeft in je
+browserprofiel, dus **de plugin bewaart geen wachtwoord** — er is niets dat kan uitlekken.
+
+Je zou dan moeten zien:
+
+1. **Instellingen → Uncle Sam** — een pagina met statusregels en een inlogknop.
+2. **Onder het invoerveld** — `● DeepSeek Harness` of `● Uncle Sam`, klik om te wisselen.
+3. **De modellenlijst** — vier `(web)`-modellen naast de API-modellen.
+
+### Verwijderen
+
+Instellingen → Plugins → Uncle Sam → Verwijderen. Buiten het browserprofiel waarmee je inlogde wordt niets
+geschreven.
+
+---
+
+## De schakelaar API / web
+
+**De modelkiezer is de schakelaar.** Er is geen tweede bediening, want een tweede bediening die ook het model
+koos zou twee bronnen van waarheid zijn voor één beslissing.
+
+| Kies dit model | Route | DeepThink | Zoeken |
+|---|---|---|---|
+| `DeepSeek Chat (web)` | browser | uit | uit |
+| `DeepSeek Chat + Search (web)` | browser | uit | **aan** |
+| `DeepSeek Reasoner (web)` | browser | **aan** | uit |
+| `DeepSeek Reasoner + Search (web)` | browser | **aan** | **aan** |
+| elk model zonder `(web)` | de API | — | — |
+
+Naast de modelnaam verschijnt een badge **WEB** of **API**, zodat de actieve route in één oogopslag zichtbaar is.
+Wordt de naam niet herkend, dan toont de badge niets in plaats van te gokken — een verkeerde badge is erger dan
+geen.
+
+Je keuze blijft bewaard na herstarts. **DeepThink** is de redeneerpass; **Zoeken** laat hem het live web lezen.
+
+### Zoeken is zichtbaar in het gesprek
+
+Met een zoekmodel levert een beurt **twee blokken** op — de zoekopdracht die hij gebruikte, de gevonden bronnen
+en dan het antwoord dat ervan gebruikmaakte:
+
+```
+Webzoekopdracht — "Wat is vandaag een technologienieuws-kop?"
+Bronnen (4): yna.co.kr · fnnews.com · rthk.hk · sina.com.cn
+Links: https://k.sina.com.cn/article_... http://www.21jingji.com/article_...
+```
+
+De pagina geeft de intern getypte opdracht niet prijs, dus de geciteerde opdracht is het bericht dat het zoeken
+startte. Bronnen en links worden van de pagina gelezen zodra het antwoord is gaan liggen. Omdat bronnen pas aan
+het eind bestaan, **worden zoekbeurten gebufferd in plaats van gestreamd**; gewone beurten streamen nog steeds
+token voor token.
+
+---
+
+## Waarom een browser, en niet hun HTTP-API
+
+De voor de hand liggende route — de eigen API van `chat.deepseek.com` aanroepen — is geprobeerd en verlaten. De
+site laat elk bericht door twee poorten:
+
+| Poort | Wat het betekent |
+|---|---|
+| `/api/v0/chat/create_pow_challenge` | een **proof-of-work** per bericht |
+| `challenges.cloudflare.com/turnstile` | een botpoort op de origin |
+
+Een van beide opnieuw bouwen is een verloren spel: ze zijn verduisterd, ze veranderen, en als ze veranderen lijkt
+de storing precies op een netwerkstoring. **De pagina lost beide al op voor zijn eigen verzoeken.**
+
+De adapter spreekt dus nooit HTTP met de site. Hij bestuurt de pagina, en de pagina doet de rest. Authenticatie,
+proof-of-work en Turnstile zijn niet langer ons probleem en kunnen niet los van de site zelf breken.
+
+**Geverifieerd:** een kale `HEAD` naar de site geeft `403`; de browserroute geeft antwoorden.
+
+---
+
+## Grenzen, eerlijk gezegd
+
+**Tool-aanroepen zijn nagebootst.** Een webchat heeft geen gestructureerd toolkanaal: tools worden in de prompt
+beschreven en een aanroep wordt teruggevonden door een JSON-object uit het antwoord te halen. Het werkt —
+geverifieerd — maar is zwakker dan native tool-aanroepen: een model dat de instructie negeert antwoordt in proza
+en de harness ziet die beurt geen toolgebruik. **Voor zwaar agentisch werk is de API-route betrouwbaarder.** De
+webroute is het best voor gesprek, lange antwoorden, subagents, compactie en elke beurt waarin het model het
+webmodel moet zijn.
+
+**Het hangt af van een website die je niet beheert.** Als de pagina van vorm verandert, moet de plugin mee. Dat is
+de waarschuwing over actieve ontwikkeling bovenaan deze pagina, geen formaliteit.
+
+**Het is niet verbonden met DeepSeek.** Het wordt door hen niet goedgekeurd of ondersteund, en het geeft je geen
+rechten op hun dienst. Jouw gebruik van die dienst valt onder hun voorwaarden.
+
+---
+
+## Configuratie
+
+`cordis.patch.yml` stelt in:
+
+| sleutel | standaard | betekenis |
+|---|---|---|
+| `port` | `9222` | de debugpoort van de browser |
+| `defaultModel` | `deepseek-chat-search` | gebruikt als een aanroep geen model noemt |
+| `showBrowser` | `true` | of het venster zichtbaar is tijdens het werk |
+
+De browser moet een ingelogde `chat.deepseek.com`-sessie hebben. De eerste aanroep start Brave met het
+**Default**-profiel als de poort nog niet open is. Draait Brave al *zonder* debugpoort, dan kan de adapter niet
+koppelen en zegt dat duidelijk in plaats van stil te falen.
+
+---
+
+## Opbouw
+
+```
+index.js          de adapter: harness StreamChunk  ←→  engine
+lib/engine.mjs    browser + pagina: typen, sturen, streamen, laten rusten
+lib/cdp.mjs       Chrome DevTools Protocol-client, geen afhankelijkheden
+lib/prompt.mjs    vlakt berichten + tools af tot één bericht; haalt tool-aanroepen uit het antwoord
+lib/savings.mjs   wat de webroute je bespaarde, geprijsd tegen de API
+lib/i18n.mjs      51 talen voor het paneel
+```
+
+**Geen afhankelijkheden.** Node 24 heeft globale `WebSocket` en `fetch`, en dat is alles wat CDP nodig heeft,
+dus de tokenstroom verlaat nooit het hostproces en er is geen IPC-sprong per delta.
+
+---
+
+## Steun
+
+Uncle Sam bestaat zodat je stopt met betalen per token. Als het je geld heeft bespaard en je de volgende op
+hardware wilt zien die niet halverwege zonder geheugen komt te zitten:
+
+**[☕ revolut.me/operatingtag](https://revolut.me/operatingtag)**
+
+Een ster op de repository of een bruikbare bugmelding is net zoveel waard.
+
+---
+
+## Licentie
+
+**CC BY-NC-ND 4.0** — Creative Commons Naamsvermelding-NietCommercieel-GeenAfgeleiden 4.0 Internationaal.
+Copyright (c) 2026 Darren T. Weldon, gepubliceerd onder de naam Operating Tag.
+
+**De hele afspraak in één regel: installeer het en gebruik het persoonlijk, gratis. Wijzig het niet, deel het
+niet, verkoop het niet en gebruik het niet in een bedrijf.**
+
+Dat is geen open source, en het doet niet alsof.
+
+```
+je mag       het installeren en draaien · het persoonlijk, niet-commercieel gebruiken
+            de broncode lezen om het te begrijpen
+
+je mag niet het wijzigen, aanpassen of er een afgeleid werk van maken
+            het kopiëren, verspreiden, publiceren, spiegelen of
+            aan iemand anders beschikbaar stellen
+            het uploaden naar welke codehost, registry, website, forum of chat dan ook
+            het verkopen, doorverkopen, verhuren of er geld voor vragen of voor toegang
+            het opnemen in iets dat je aan iemand anders levert
+            het gebruiken voor enig commercieel doel of in het kader van een bedrijfsactiviteit
+```
+
+**De enige twee legitieme bronnen zijn deze repository en het npm-pakket
+[`@operatingtag/dsh-unclesam`](https://www.npmjs.com/package/@operatingtag/dsh-unclesam).** Een kopie van
+ergens anders is niet gelicentieerd, wie hem ook heeft geleverd. Zie je deze software te koop, dan verkoopt niet de
+auteur hem.
+
+**Commercieel gebruik, en het recht om te wijzigen en te verspreiden, zijn beschikbaar onder een aparte
+schriftelijke licentie.** Vraag Operating Tag en je krijgt een duidelijk antwoord en een duidelijke prijs.
+
+Het bestand [LICENSE](LICENSE) is bindend, en het begint met dezelfde samenvatting in eenvoudig Engels.
+
+---
+
+Uncle Sam is een onafhankelijke plugin. Niet verbonden met DeepSeek, door hen niet goedgekeurd of ondersteund.
+
+```
+@operatingtag/dsh-unclesam   v1.0.1
+Auteur    Operating Tag
+Licentie  CC BY-NC-ND 4.0 — vrij om te gebruiken, niet om te wijzigen, delen of verkopen
+```