@operatingtag/dsh-unclesam 1.0.0 → 1.1.0

package/README.md

@@ -1,7 +1,10 @@
-# Uncle Sam — a harness model provider that drives chat.deepseek.com
+**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) · [ไทย](README.th.md) · [فارسی](README.fa.md) · [Ελληνικά](README.el.md) · [עברית](README.he.md) · [Čeština](README.cs.md) · [Română](README.ro.md) · [Svenska](README.sv.md) · [Dansk](README.da.md) · [Suomi](README.fi.md) · [Magyar](README.hu.md)
 
-**☕ [Buy me a coffee](https://revolut.me/operatingtag)** — this is 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.
+# 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.**
 >
@@ -9,38 +12,41 @@ nothing. There is no other revenue model. A star or a bug report is worth just a
 > 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.
 
-## Contents
-
-- [Installing](#installing)
-- [Why it is built this way](#why-it-is-built-this-way)
-- [Architecture](#architecture)
-- [Tool use is emulated](#tool-use-is-emulated-and-that-is-a-real-limitation)
-- [Configuration](#configuration)
-- [The API-vs-web switch](#the-api-vs-web-switch)
-- [Testing](#testing)
-- [Licence](#licence)
-
-Not affiliated with DeepSeek. It drives their public web product exactly as a person would.
-
-Adds **`deepseek-web`** as a model provider. A real browser answers each call, so the model runs on the
-web account already open in a tab — no API key, no per-token billing.
-
-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.
-
 ```
 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 slots. Installing it into anything else will simply do nothing visible.
+provider, a host route and two client UI slots.
 
 **Requirements**
 
@@ -50,12 +56,20 @@ provider, a host route and two client slots. Installing it into anything else wi
 | Browser | Brave recommended, Edge used automatically when Brave is absent |
 | Node | 22 or newer |
 
-**From a package registry, once published**
+**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
@@ -65,109 +79,99 @@ Then add the bundle row to your profile so the harness loads it:
       name: '@operatingtag/dsh-unclesam'
       config:
         port: 9222
-        defaultModel: deepseek-chat
+        defaultModel: deepseek-chat-search
         autoMinimise: true
 ```
 
-**From a folder**
-
-```
-Settings → Plugins → install from a local path
-```
-
-pointed at the folder containing `package.json`.
+**Or from a folder:** Settings → Plugins → install from a local path, pointed at the folder holding
+`package.json`.
 
-**What you should see afterwards**
-
-1. **Settings → Uncle Sam** — a page with four status rows and a sign-in button.
-2. **Under the chat box** — `● DeepSeek Harness` or `● Uncle Sam`, click to switch.
-3. **The model list** — `deepseek-chat (web)` and `deepseek-reasoner (web)` beside the API models.
-
-**First run**
+### 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.
+browser profile, so **no password is stored by the plugin** — there is nothing to leak.
 
-**Removing it**
+You should then see:
 
-```
-Settings → Plugins → Uncle Sam → Uninstall
-```
+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.
 
-Nothing else is written outside the browser profile you signed in to.
+### Removing it
 
----
+Settings → Plugins → Uncle Sam → Uninstall. Nothing is written outside the browser profile you signed in to.
 
-## Why it is built this way
+---
 
-The obvious route — call `chat.deepseek.com`'s own HTTP API — was attempted and abandoned, because the
-site makes every message clear two gates:
+## The API / web switch
 
-| 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 |
+**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.
 
-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.**
+| 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 | — | — |
 
-So the adapter never speaks HTTP to the site. It drives the page, and the page does the rest. Auth, PoW
-and Turnstile stop being our problem and cannot break independently of the site itself.
+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.
 
-**Verified:** a plain `HEAD` to the site returns `403`; the browser path returns answers.
+Your choice persists across restarts. **DeepThink** is the reasoning pass; **Search** lets it read the live web.
 
----
+### Search is visible in the transcript
 
-## Architecture
+With a search model, a turn produces **two blocks** — the query it searched with, the sources it found, then
+the answer that used them:
 
 ```
-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
+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_...
 ```
 
-Nothing is installed as a dependency. 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.
+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.
 
-### The four failures that shaped the code
+---
 
-Each of these was observed, not anticipated, and each is now guarded by a comment at the site.
+## Why a browser, and not their HTTP API
 
-1. **The answer arrived with the previous answer glued to the front.** The reader took the last
-   "message-ish" block, and after a failed *New chat* click the previous transcript was still there.
-   Fixed twice over: the reset is now *verified* (count of assistant blocks must reach zero), and the
-   reader takes a **baseline index** so only blocks created after the prompt can ever be returned.
+The obvious route — calling `chat.deepseek.com`'s own API — was attempted and abandoned. The site makes every
+message clear two gates:
 
-2. **The answer was emitted twice.** The DOM held it once; the adapter's fallback branch re-emitted the
-   whole text for a non-prefix change and the consumer appended it. Deltas now emit **only characters
-   not yet sent**, computed by longest common prefix. A streaming adapter may never resend text.
+| 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 |
 
-3. **A `zoompan`-style trap in miniature:** `waitFor` called its probe without a catch, so waiting for the
-   browser's debug port died on the first `fetch failed` — the normal state for several seconds.
-   A throw inside the poll now means "not ready yet".
+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.**
 
-4. **The tool call JSON leaked into the transcript.** Tool calls are JSON, so a reply beginning with `{`
-   or a fence is now *buffered*; prose streams immediately, and only a buffered JSON reply is turned
-   into a tool call. `committed text == concatenated deltas` is asserted in the test.
+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.
 
-## Tool use is emulated, and that is a real limitation
+---
 
-A web chat has no structured tool channel. Tools are described in the prompt, and a call is recovered by
-parsing a JSON object out of the reply:
+## Limits, stated honestly
 
-```
-{"tool": "get_weather", "arguments": {"city": "Madrid"}}
-```
+**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.
 
-**This works** — verified returning `get_weather({"city":"Madrid"})` with `finish: tool-calls`.
+**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.
 
-**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 provider is more reliable; this
-provider is best for chat, subagents, compaction, and any turn where the model must be the *web* model.
+**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.
 
 ---
 
@@ -178,102 +182,35 @@ provider is best for chat, subagents, compaction, and any turn where the model m
 | key | default | meaning |
 |---|---|---|
 | `port` | `9222` | the browser's debugging port |
-| `defaultModel` | `deepseek-chat` | used when a call names no model |
+| `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 reports that clearly.
+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.
 
 ---
 
-## The API-vs-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 | Provider | 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 would
-be worse than none.
-
-### Search is visible in the transcript
-
-With a search model, a turn produces **two blocks**:
+## Architecture
 
 ```
-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_...
-```
-
-then the answer that used them. The page does not expose the query it typed internally, so the quoted
-query is the prompt that triggered the search; the sources and links are read from the page after the
-answer settles, from the `cdn.deepseek.com/site-icons/<domain>` favicons and the external citation
-anchors. Because the sources only exist once the answer is finished, **search turns buffer instead of
-streaming**; non-search turns still stream token by token.
-
-### The two switches
-
-`DeepThink` is the reasoning pass; `Search` lets it read the live web. Both are per-conversation and are
-cleared by *New chat*, which is why the engine sets them **after** the reset and **before** typing. They
-are also re-read after clicking, because a click is a request rather than a result.
-
----
-
-## Testing
-
-```bash
-node test-adapter.mjs              # prose path: contract checks
-node test-adapter.mjs --tools      # tool path: JSON must not reach the text channel
-node test-search-adapter.mjs       # search path: two blocks, query + sources + answer
-node test-engine.mjs "prompt"      # raw engine timings
-DEBUG_WEB_CHAT=1 node test-engine.mjs "prompt"   # per-poll trace
+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
 ```
 
-`test-adapter.mjs` enforces the three rules that matter: a block is opened before any delta, exactly one
-terminal `finish`, and committed text equals the concatenated deltas.
-
----
-
-## Verification status
-
-| Claim | Evidence |
-|---|---|
-| Engine drives the page end to end | measured across several prompts |
-| Adapter emits a valid chunk sequence | `test-adapter.mjs` — **passes** |
-| Search emits query + sources + answer | `test-search-adapter.mjs` — **passes**, 4 domains + links, 5.0 s |
-| Tool emulation recovers a call | **passes**, `get_weather({"city":"Madrid"})` |
-| Bundle installs and activates | `application: applied`, v1.1.0 |
-| Row composed into the profile | present in `dsh.profile.bundles` |
-| Client half present with `dsh.client` | `client.js` + `platform: web`, `inject` conversation UI |
-| **Model selectable in the GUI** | **not visually verified** — the Web UI answers a bare origin with `dsh web authentication required; reopen the URL printed by dsh web`, and that URL is not recoverable from this session |
-| **The WEB/API badge rendered** | **not visually verified** — same reason |
-| **A live harness turn** | **not run** — needs a model selected in the picker |
-
-The last three need the harness restarted by the user and one model chosen; they cannot be closed from
-inside the running session.
-
----
-
-## Changelog
-
-Every released version, newest first, in [CHANGELOG.md](CHANGELOG.md).
+**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 to stop you paying per token. If it has saved you money, and you would like to see the
-next one built on hardware that does not run out of memory halfway through, you are welcome to buy me a
-coffee:
+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)**
 
@@ -289,67 +226,36 @@ 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. It is a free personal-use grant over software you may
-not copy or modify.
-
-### What you may do
+That is not open source, and it does not pretend to be.
 
 ```
-install it from its official source and run it
-use it for personal, non-commercial purposes
-read the source to understand how it works
-keep it installed for as long as you like
+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
 ```
 
-### What you may not do
+**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.
 
-```
-modify, adapt, translate or create a derivative of it
-copy, distribute, publish, mirror or make it available to anyone else
-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 official sources
-
-**Exactly two places** may legitimately supply this software:
-
-```
-the GitHub repository operated by Operating Tag
-the npm 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.**
-
-### If you need more than that
-
-Commercial use, and the right to modify and distribute, are available under a **separate written licence**.
+**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 is what actually governs, and it opens with the same summary in plain English
-before the licence text.
-
-### The ask
-
-This is written by one person, at night, funded by nothing. Fifty-one languages were written out by hand and
-each was tested until it behaved. There is no other revenue model.
-
-If it saved you money or an afternoon:
-
-**[☕ revolut.me/operatingtag](https://revolut.me/operatingtag)**
-
-That is a **request, not a condition.** It carries no legal weight, and ignoring it changes nothing about your
-rights.
+The [LICENSE](LICENSE) file governs, and it opens with the same summary in plain English.
 
 ---
 
-Uncle Sam is an independent plugin. It is not affiliated with, endorsed by, or supported by DeepSeek.
+Uncle Sam is an independent plugin. Not affiliated with, endorsed by, or supported by DeepSeek.
 
 ```
-@operatingtag/dsh-unclesam   v1.0.0
+@operatingtag/dsh-unclesam   v1.1.0
 Author   Operating Tag
 Licence  CC BY-NC-ND 4.0 — free to use, not to change, share or sell
 ```