clauderipple 0.9.5 → 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
@@ -772,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
@@ -816,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
@@ -1157,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`
@@ -1225,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
@@ -1291,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
@@ -1439,6 +1537,8 @@ plan unless marked otherwise.
 | 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.5",
+  "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"
   }