clauderipple 0.9.4 → 0.10.0

package/docs/ARCHITECTURE.md

@@ -46,6 +46,41 @@ Why this path is stable:
 - The CA is never installed in the keychain. `NODE_EXTRA_CA_CERTS` is a Node-only
   trust addition, no admin password, no effect on other programs.
 
+### 1a. Remote (SSH) sessions (2026-10-20, issue #67)
+
+A Code-tab session on a remote host runs Claude Code **on that host**, started by
+Desktop's remote server with `--setting-sources user,project,local`, so the
+host's own `~/.claude/settings.json` applies and its 127.0.0.1 is itself. Desktop
+opens that connection with its bundled `ssh2` library, uses only `forwardOut`
+(local → remote), and never reads `RemoteForward` from `~/.ssh/config` (verified
+for #67). Nothing Desktop does can carry the host's traffic back to us, so the
+router holds its own reverse tunnel: `ssh -N -o ExitOnForwardFailure=yes -R
+127.0.0.1:<remote port>:127.0.0.1:<proxy port> <host>` per configured host
+(`remote.hosts`, `packages/router/src/remote-tunnel.ts`), with the user's own ssh
+and keys (`BatchMode=yes`: never a prompt). `clauderipple remote add` writes the
+same two env keys as §1 into the host's settings.json (same foreign-proxy rule,
+one backup), the public CA to `~/.clauderipple-remote/ca.pem`, and the generated
+agent files, all by POSIX `sh` scripts on ssh's stdin — the host needs no Node.
+The host name is validated and only ever passed as its own argv element.
+
+- Up is when ssh says `remote forward success for: listen …` (it needs `-v`;
+  every other debug line is dropped before the log). A dropped tunnel restarts
+  with 1s→60s backoff; each comeback re-copies the CA and agent files, and the
+  config callback re-copies them when the router regenerates the agents.
+- While the tunnel is down, the host's Claude Code gets *connection refused* —
+  a visible error, never a silent route to Anthropic around the router. The
+  remote session only exists while this machine's Desktop is connected anyway.
+- Tunnels are killed at process exit, not when a drain starts: a remote
+  session's in-flight model call travels through one (§5, drain). Their pids are
+  kept in `<home>/remote-tunnels.json` and a new router kills any that still run
+  with our command line — an orphan holding the remote port would make every new
+  tunnel fail `ExitOnForwardFailure` for as long as it lives.
+- `clauderipple remote remove` stops the tunnel, removes only the env values
+  that are still ours, the agent files listed in the host's
+  `~/.clauderipple-remote/agents.json`, and that directory.
+- Not yet on remote hosts: the status mod, the `cli.models` slot env, and image
+  generation (generated agents name the admin port, which is not tunnelled).
+
 ## 2. What the app does with the official third-party setting (why competitors lose)
 
 ### Optional Auto mode classifier target
@@ -731,8 +766,13 @@ must preserve **Data: Artificial Analysis (artificialanalysis.ai)** attribution.
   - `WebFetch` needs none of this: the CLI fetches the URL itself (its own transport, cache and
     preflight; there is no `web_fetch` server tool in the binary) and has the session's model read
     the text. It works on any provider.
-  - Cache-safety decisions: thinking blocks are dropped from replayed history;
-    no reasoning `include`; identity line and `instructionsAppend` are constant
+  - Cache-safety decisions: a translated provider's own reasoning that comes back with the
+    request is sent back **byte-identically, in its original position** — that is what the
+    vendor's native clients do, and it is not a `cache_control` breakpoint; the forbidden
+    thing is *altering or re-signing* reasoning, which is what cost 12–20% cache (2026-09-20).
+    A thinking block of ours that names no vendor model, or another model than this request's,
+    is dropped (§5, "Muse workers"); foreign thinking of any other kind is dropped from
+    replayed history; identity line and `instructionsAppend` are constant
     text; `prompt_cache_key` = sha256(metadata.user_id + first user message),
     and sha256(system prompt) for a request that carries no `metadata.user_id`
     and one lone user turn — see the conversation-key note in §4.
@@ -767,11 +807,29 @@ text is added. Source: `requestlog.ts`, `proxy.ts`, provider adapter outcomes.
 - `upstreamRequestId`: the final forwarded native Anthropic response's `request-id` header (passthrough or account pool).
 - `messageId`: the Anthropic message id delivered by a translated adapter or forwarded compatible response; not a generated id from a non-streaming error.
 - `upstreamCalled`: `false` only for a known pre-model-API exit; omitted when a search backend was attempted or the call state is unknown.
-- `refusal`: `thread-continue`, `drain`, `unroutable`, `no-account`, `unknown-provider` or `web-search-unsupported`, from the actual exit branch.
+- `refusal`: `thread-continue`, `drain`, `unroutable`, `no-account`, `unknown-provider`, `web-search-unsupported` or `prompt-incompatible`, from the actual exit branch. `prompt-incompatible` follows an upstream request; it does not set `upstreamCalled: false`.
 - `purpose`: `auto-mode-classifier` from the security-monitor request shape regardless of routing settings, or `web-search` for router-served searches.
 - `requestedTier`: the service tier actually sent upstream, including ChatGPT's `speed: "fast"` → `priority`; omitted when no tier was sent.
 - `servedTier`: the response-reported tier (Responses/Chat `service_tier` or Anthropic `usage.service_tier`); never inferred from the request.
 
+**Hourly usage history (`usage-hourly.jsonl`, 2026-10-20).** `requests.jsonl` is
+bounded (2,000 records in memory, 20 MB plus one `.1` backup), so the GUI could only
+summarise about an hour. `RequestLog` now also owns a `UsageHistory` that appends one
+JSON line per `(hour, provider, model)` partial bucket —
+`{"h": floor(at/3600000), "p", "m", "count","ok","failed","input","cached","cacheWrite","output","ms"}`
+— to `usage-hourly.jsonl` beside `requests.jsonl`. Lines are **additive**: reading
+sums every line with the same `(h,p,m)`, so the file stays append-only. Only the
+**open hour** (the newest record's hour) lives in memory; when the hour advances its
+buckets are flushed, and a late record whose hour is below the open hour is written
+at once as its own line. On startup the highest hour in the file is the watermark and
+request records above it are replayed from `requests.jsonl` (and `.1` when its mtime
+hour is above the watermark — not the first record of `requests.jsonl`, which a long
+request straddling the rotation makes older than records left in `.1`), so the open
+hour survives a restart without an hour being counted twice. An fs error is swallowed: history must never alter the response path.
+`GET /api/requests/summary?from=&to=` reports `{total, providers, models, earliest,
+from, to}` at hour granularity — buckets whose hour start is in `[from, to)`. Source:
+`usage-history.ts`.
+
 - **Server-side threads ("tether").** The first request of a session carries
   `thread: {type:"create"}` and the full history; later turns carry
   `thread: {type:"continue", previous_message_id: <our last assistant msg id>}` and
@@ -811,6 +869,9 @@ text is added. Source: `requestlog.ts`, `proxy.ts`, provider adapter outcomes.
   is parked, the turn goes to the first fallback that has one, chosen **before anything is sent**,
   since failing over mid-turn would splice two answers together. With nothing usable anywhere the
   primary is kept, so the provider refuses rather than the router inventing a refusal.
+  The narrowly classified Antigravity prompt refusal (§4d-ii) additionally permits one same-turn
+  route fallback after the upstream rejects the request but **before any response reaches the
+  client**; it does not mark a usable account as exhausted.
   - Four things an independent review found, each of which had made it past the unit tests because
     each lived in the wiring rather than the state machine: the pool never heard about the ChatGPT
     or openai-compatible adapters, so those providers looked healthy forever and a slot pointing at
@@ -1061,9 +1122,11 @@ what we do not have yet — so that adding a provider does not start with readin
   config still written as three providers is folded on the way in and its `direct` and
   `routes` references follow; nothing is rewritten on disk, so it stays readable by an
   older router until the GUI saves it.
-- Translation deliberately strips `thinking`, `context_management`, `thread`,
+- Translation deliberately strips `context_management`, `thread`,
   `diagnostics`, and `container`; `thread:continue` is refused exactly as in §4a so
-  the CLI resends a full stateless history. The per-turn
+  the CLI resends a full stateless history. Thinking is stripped by default too —
+  except the reasoning this adapter itself handed out, which returns as the vendor's
+  own item (see the reasoning-replay note below). The per-turn
   `x-anthropic-billing-header` system block is also stripped because its changing
   value breaks every vendor's stable-prefix cache opportunity. Orphan tool results
   are sent as user text, not a tool result with no antecedent call.
@@ -1085,6 +1148,50 @@ what we do not have yet — so that adding a provider does not start with readin
   before (`catalog.ts`, `capabilities.ts`). Chat wire
   forwards Anthropic `stop_sequences` as `stop`; Responses wire deliberately omits
   them because its common stateless schema has no corresponding universal field.
+- **Reasoning replay (both wires, 2026-10-14).** A reasoning model on either wire
+  expects its own previous reasoning back on the next turn of a tool loop, and does
+  badly without it. Measured on OpenCode Go's Muse at `xhigh`, same task, 3 runs
+  each: with no replay 9.5k–24.5k reasoning tokens per run (2,197 per step past 80k
+  context) and one run exhausted the context with no answer; with replay 3.2k–4.3k
+  per run (725 per step past 80k) and all three answered, 94% cached.
+  Native clients (OpenCode, the Codex CLI) do this by carrying the vendor's item in
+  their own transcript and putting it back byte-for-byte where it was.
+  Claude Code's transcript is the same medium, so the carrier is the **signature of a
+  thinking block**: `reasoning.ts` encodes `clauderipple.v1:` + base64url JSON
+  naming the wire, provider and model and the thing to restore — the vendor's whole
+  Responses item for the Responses wire, or just the field name
+  (`reasoning_content` / `reasoning`) for Chat. On the Responses wire the item is
+  `{type:"reasoning", id, summary, encrypted_content}` and the request asks for it
+  with `include:["reasoning.encrypted_content"]` (with `store:false` and
+  `reasoning.summary:"auto"`, both of which the chatgpt adapter already sent); the
+  block's text is the summary, or empty when the item had none. `include` is sent on
+  every turn to the ChatGPT backend (as Codex sends it) and to a preset marked
+  `sealedReasoning` (OpenCode Go, as OpenCode's own client sends it): a `store:false`
+  backend that is not asked hands back nothing, so asking only once a conversation
+  already carried reasoning would never start one. Any other Responses vendor is asked
+  only once its own reasoning is already being carried, so an unmeasured vendor keeps
+  its old request. Measured 2026-10-14 against OpenCode Go: the sealed item came back
+  with `include` and without it (1426 bytes either way), replaying it in place
+  answered 200, and the vendor tolerated both a tampered blob and a dropped item. On Chat the
+  block's own text *is* the reasoning and it is reassembled into the field it arrived
+  under on that assistant message — DeepSeek's docs make that mandatory whenever
+  `tools` is present (`https://api-docs.deepseek.com/guides/thinking_mode/`), and it
+  is harmless where a vendor ignores it, so this is not gated by an allowlist.
+  Restore happens only when the envelope names this request's provider and model
+  (model scope validation): another model's or account's `encrypted_content` is a
+  400, and the envelope says whose it is. This is not exposed as a setting, and it
+  does not weaken the cache lesson above — the vendor's bytes are re-sent unchanged,
+  never re-signed or edited. `opencodex` (github.com/lidge-jun/opencodex,
+  `devlog/_fin/260711_claude_inbound/003_evidence.md:93-118`) uses the same
+  envelope-in-the-transcript approach and measured that Claude Code replays thinking
+  blocks with their signature and does not validate it client-side; no code was
+  copied from it. A 4xx that names reasoning/encrypted/item is answered by asking
+  **once more without any replayed reasoning**, so an account switch that invalidates
+  `encrypted_content` costs a little cache and not the turn. `router.log` and
+  `requests.jsonl` carry `replayed=<n>` (items put back) and `reasoning=<n>` (items
+  handed to the client). Gemini and the other translators strip these blocks; a
+  conversation switched to a Claude model does too (`thinking.ts`), since Anthropic
+  would reject a foreign signature.
 - We do not assert a provider-wide cache hit rate: the adapter records
   `prompt_tokens_details.cached_tokens` / `input_tokens_details.cached_tokens` when
   a vendor returns it, and otherwise logs zero cache read. The byte-stable
@@ -1106,9 +1213,10 @@ adapter lives in `packages/router/src/providers/google/` and separates translati
 (`thoughtSignatures.ts`) so Stage 2 (Antigravity Code Assist) is a new transport only.
 
 Both modes are implemented: `api-key` (AI Studio) below, and `auth: "antigravity"` (Cloud
-Code Assist) in its own subsection. No live key or Antigravity subscription exists in this
-environment, so everything below is doc- and source-derived and **not measured** unless it
-says otherwise:
+Code Assist) in its own subsection. At the original implementation on 2026-10-01, no live
+key or Antigravity subscription was available in the implementation environment, so those
+initial facts were doc- and source-derived, **not measured**. Later dated observations,
+including the 2026-10-16 Antigravity measurement in §4d-ii, are identified separately:
 
 - Stream endpoint `POST {base}/v1beta/models/{model}:streamGenerateContent?alt=sse`,
   the key on header `x-goog-api-key`, base default `https://generativelanguage.googleapis.com`
@@ -1174,10 +1282,10 @@ Cloud Code Assist (CCA) backend, with several accounts rotating. Same translatio
 Studio; only `transport.ts` differs. Accounts live in `<home>/google-accounts.json` (0600,
 cross-process lock, atomic write, one account per email+project, a re-login replaces its own
 entry), the sign-in in `login.ts`, the account pool and refresh in `accounts.ts`, and the wire
-facts and model-id resolution in `antigravity.ts`. **Every wire fact below is taken from the
-reference implementation opencodex (GitHub `lidge-jun/opencodex`, read 2026-10-01 as a
-behavioral spec — no code copied; project rule) and is not measured live** — no Antigravity
-subscription exists in this environment. Files are under `src/`:
+facts and model-id resolution in `antigravity.ts`. **Except for the dated live observation
+below, these wire facts come from the reference implementation opencodex** (GitHub
+`lidge-jun/opencodex`, read 2026-10-01 as a behavioral spec — no code copied; project rule).
+They were not live-tested during the original implementation. Files are under `src/`:
 
 - OAuth is Google's standard installed-app flow with PKCE S256. Client id
   `1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com`, secret
@@ -1240,6 +1348,47 @@ subscription exists in this environment. Files are under `src/`:
   and is not retried. Refresh is per account, single-flight per token generation, five minutes
   ahead; only a structured `invalid_grant` marks an account for sign-in. Only the access token
   and the account email/project id are ever in memory; no token reaches a log or an API response.
+- **SDK prompt refusal (measured 2026-10-16, Windows, Claude Code 2.1.289).** The Opus request
+  used the CCA wire id `claude-opus-5-5-high` unchanged, with
+  `generationConfig.thinkingConfig.thinkingLevel: "low"` (not an id from the static fallback
+  table). The Gemini comparison used picker id `gemini-3.8-flash`, effort `low`, resolved by
+  `resolveAntigravityWireModel` to wire id `gemini-3.8-flash-low`, without a separate
+  `thinkingConfig`. The saved comparison records the Opus id and both generation configs;
+  Gemini's wire id is reconstructed from the reproduction script's inputs and the resolver,
+  not a captured outbound envelope. Both requests used `maxOutputTokens: 128000`.
+  Otherwise identical requests returned HTTP 429 with the standalone system paragraph
+  `You are a Claude agent, built on Anthropic's Claude Agent SDK.` and HTTP 200 without it.
+  The paragraph alone reproduced the refusal; reducing output tokens did not. OAuth, project
+  discovery and short compatible requests succeeded on the same account. This establishes a
+  request-specific refusal in that measurement, not Google's internal policy or every account's
+  quota. Related independent reports: [OpenCodex #2899](https://github.com/lidge-jun/opencodex/issues/2899),
+  [Magpie #666](https://github.com/yetone/magpie/issues/666).
+  The SDK paragraph alone does not distinguish refusal from exhaustion: SDK clients send it on
+  every request, and Google can use the same generic 429 for real limits. `prompt-refusal.ts`
+  checks the outbound paragraph, exact generic `RESOURCE_EXHAUSTED` JSON, and absence of a
+  retry header or nonempty error details. The adapter additionally requires a **fresh successful
+  usage snapshot for the attempted account and project**, with quota remaining in both the 5h
+  and weekly windows of the requested model's known quota group (Gemini or Claude/GPT).
+  Evidence expires after five minutes or a bucket's reset time, and a failed refresh invalidates
+  it even when the dashboard retains old values. Missing, malformed, ambiguous, stale or exhausted
+  evidence follows ordinary 429 cooldown/account rotation. This is a cache-only check; it does
+  not probe quota per request. Group-level quota is supporting evidence, not proof about every
+  model or concurrent request; unknown groups/models are not classified.
+  With that evidence the adapter leaves the prompt intact and returns a distinct **unwritten**
+  `prompt-incompatible` outcome, without cooling the account or trying the prompt on its peers.
+  Before any response bytes, the proxy tries the same request once on the first usable configured
+  route fallback other than the attempted provider/model pair. Each attempt starts from the
+  original request and applies the target's own model, effort and translation. Another model on
+  the same provider is eligible; no fallback chain or unconfigured provider is tried. An absent
+  usable fallback, or a second prompt refusal, produces the explanatory `400 invalid_request_error`.
+  Other fallback errors keep their normal handling. A successful fallback's request record names
+  the actual responder and retains the initial upstream 429/refusal in its note, without marking
+  the successful turn as refused. A terminal refusal records `refusal: prompt-incompatible`.
+  Another compatible request can still use the primary account immediately. The message makes
+  no claim that changing accounts cannot help: only one account was measured.
+  This is error handling, not a workaround that makes Google accept the SDK prompt. HTTP-200
+  error frames were not part of this live reproduction and retain the existing stream handling;
+  no fallback can replace an answer once response bytes have been sent.
 - Session id and prompt cache. The real client puts a stable per-conversation id at
   `request.sessionId` so provider-side replay can associate a signature with the call that made
   it; instability loses it (`google-antigravity-wire.ts:62-88`). We derive it from the router's
@@ -1386,7 +1535,10 @@ plan unless marked otherwise.
 | Adding a provider in the settings window restored three OpenCode effort ladders realigned by hand five hours earlier, so the app's effort menus for DeepSeek and GLM never narrowed (2026-10-02 23:13, found 10-05). `PUT /api/config` takes the whole config, and the screen built it from the copy it loaded at open and never re-read; the router itself also writes `config.json` (a measurement's results), so any of those was undone by the next unrelated save | Every GUI save fetches the router's config first and applies its own change to that. A provider form, which holds per-model fields (wire, ladder, window) from when it opened and has no control for them, takes a saved model's values from the router's copy. The provider and client screens re-read the config whenever they load. |
 | In picker mode, claude.ai requests failed as `502 … ECONNRESET` in under a second — 259 times in four days (2026-10-03..06), mostly `current_user_access`, `desktop/features` and `event_logging`. The kept-alive upstream socket had been closed by claude.ai as the next request was written on it, and Node does not resend | A GET/HEAD/OPTIONS whose reused socket resets before any response is sent again (twice at most), logged `STALE`. A POST is never resent: a reset does not prove the upstream did not act on it. Not yet shown to be the cause of the Windows "chat history loads forever" report (DC, 2026-10-06). |
 | An API-key provider with no declared effort ladder — DeepSeek, Kimi, GLM, MiniMax, Qwen, Groq, Mistral, a key and a URL — stripped every effort the user picked (`effort high→removed`) and the Claude app showed no effort menu for its models (DC reports, 2026-10-06). Declaring nothing was meant as "do not guess", but DeepSeek's API, for one, validates `output_config.effort` and maps it onto low/high/max | When nothing declares a ladder (no config ladder, no preset ladder, OpenAI-compatible `reasoning` not `effort` — the form writes `none` by default), a measurement sends a level no vendor defines first: accepted means the field is ignored (no effort, `[]`); refused means it is validated, and the levels the refusal names (else every known one) are sent one by one and the accepted ones become the model's ladder. A 429/5xx concludes nothing. The router runs this a minute after start for unsettled models, so existing providers need no re-save. The DeepSeek preset now declares low/high/max from its docs. |
+| Muse workers spent minutes per tool call, repeated the same reasoning every step, and one ended with no answer at all (2026-10-14). A reasoning model on a translated wire was getting its own previous reasoning dropped, so each step reasoned the whole problem again from scratch: measured at `xhigh` on OpenCode Go, 9.5k–24.5k reasoning tokens per run without replay against 3.2k–4.3k with it (3 runs each; 2,197 against 725 per step past 80k context; one no-replay run exhausted the context) | The vendor's reasoning is carried in the client's transcript and put back byte-identically at its original position: the Responses item whole, under `include:["reasoning.encrypted_content"]`, and on Chat its text as `reasoning_content`. `reasoning.ts` states the envelope; a block whose envelope names another provider or model is dropped, and a 4xx naming the reasoning is retried once without it. |
 | ChatGPT accounts that had bought Codex credits were rested by the router the moment a window read 100%, though OpenAI serves them from credits past the window | `exhaustedForMs` ignores a full window while `credits.has_credits` or `unlimited` holds (and `overage_limit_reached` does not); an actual 429 still rests the account until the window resets. |
+| After ~120 host↔relay reconnects no phone could connect for minutes — web and native sat at "connecting" while the host's control socket was open and answering pings, and a host restart did not help (the simulator's own log: every attempt 19:10–19:17 timed out waiting for the relay's `open`, then the next one worked with no change on the phone; 2026-10-15). Measured on the deployed relay with throwaway server ids: a replaced host control socket whose other end never answers the close stays in `getWebSockets("host")`, in acceptance order, for 8+ minutes, and the room sent every phone's `connect` to `sockets("host")[0]` — that dead socket — through any number of reconnects and a restart | The room routes a phone only to the **newest** host socket (each is tagged `at:<accepted ms>`), and only while it pinged within `HOST_SILENT_MS` (the runtime's auto-response timestamp); a silent newest socket is closed `4408` and the phone hears `4404 host offline` at once. The host walks the phone's path itself after every hello and every 5 min (a client socket to its own room must come back `open` within 10 s) and reconnects when it does not; a ping timer that ran late (sleep, blocked event loop) is not taken for a dead socket. Close codes, reasons and ISO timestamps are in `host.log`. In-process tests reproduce the sequence over a network that keeps dead sockets listed (`relay-reconnect.test.ts`). |
+| An expired Claude login on the Mac wrote `[desktop state] …로그인이 만료되었습니다…` every few seconds per Claude app session and read the keychain (a synchronous child process) for every request, while phones learned of it only by a failed send (2026-10-15) | A login problem is one host state: logged when it starts and ends, sent to phones as `HostInfo.desktopProblem` (a banner), and the keychain is reread at most every 30 s while expired or after a 401. Per-session Remote Control errors log once per change. The host never refreshes the login itself. |
 
 ## 6. Blocked paths (measured, do not retry)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clauderipple",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Use GPT (any ChatGPT plan with Codex), DeepSeek and 400+ other models in the Claude Desktop Code tab and Claude Code while staying signed in to your Claude subscription — no third-party gateway mode. Several ChatGPT accounts that take over when one runs out, in Codex too.",
   "license": "GPL-3.0-only",
   "workspaces": [
@@ -77,6 +77,12 @@
     "url": "https://github.com/PBJ-2/clauderipple/issues"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.283",
+    "qrcode-generator": "2.0.4",
+    "tweetnacl": "1.0.3",
+    "web-push": "3.6.7",
+    "ws": "8.21.3",
+    "zod": "4.1.12",
     "proper-lockfile": "^4.1.2",
     "undici": "7.24.4"
   }