@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.34

package/docs/account-login.md

@@ -0,0 +1,44 @@
+# DeepSeek account login
+
+DSCODE can authenticate the DeepSeek route with a **DeepSeek account** instead of an API key. The sign-in happens in your system browser; the grant is stored on this machine and the model route picks it up automatically.
+
+`/account` is the whole surface:
+
+```
+/account            status: is a grant stored, whose account it is, what the balance is
+/account login      open the browser and complete a sign-in
+/account cancel     abandon the sign-in that is in progress
+/account logout     remove the grant from this machine
+```
+
+## What happens during a login
+
+1. DSCODE asks the account service to start an attempt, passing a loopback callback origin (`http://127.0.0.1:<port>`) and identifying itself as a desktop client.
+2. The service asks the platform to initialise the attempt with a PKCE challenge, then publishes the browser URL. DSCODE waits for that URL — it does not exist yet when the attempt is created — and only then opens the browser. If the browser cannot be launched, the URL is printed to open by hand.
+3. You sign in on the platform page. The browser is redirected to `http://127.0.0.1:<port>/oauth/callback`, where the account provider validates the `state`, exchanges the code once, and commits the grant to the local credential store.
+4. `/account` reports the outcome. A failure names a safe reason (unreachable platform, unexpected answer, timed out, credential store refused) and stores nothing.
+
+The attempt is bounded on both sides: the platform's own expiry and DSCODE's five-minute wait. `Esc` (which cancels the command) or `/account cancel` in another turn ends it, and a cancelled attempt cannot be completed by a late callback.
+
+## The callback server
+
+The account provider registers `/oauth/callback` on the Host's HTTP server, so the TUI profile composes one: `@deepseek-ai/dsh-host-webserver` on `127.0.0.1` with an OS-assigned port. It listens for the whole session but carries **no routes except during a login attempt** — the callback route is added when an attempt starts and removed when it settles, and this profile mounts none of the Web shell's frontend or API rows. Requests to anything else answer 404, and a callback without a valid `state` and `code` answers 400.
+
+Set `DSCODE_ACCOUNT_LOGIN=0` to remove the listener entirely. `/account login` then refuses with that reason instead of starting an attempt the browser could not complete; every other subcommand keeps working.
+
+## What the login is worth
+
+- **The DeepSeek route needs no API key.** The route resolves the account grant for the configured inference origin (`https://api.deepseek.com` by default) and sends it as the request credential. A `DEEPSEEK_API_KEY`, or a key stored through `/login`, keeps working and is what the route falls back to when no grant is stored.
+- **A grant is scoped to one origin.** If you point the DeepSeek route at a proxy or another base URL, the account token is deliberately not sent there; use an API key for that route.
+- **Identity and balance come from the platform**, not from DSCODE: `/account` prints the account name and masked contact, the recharge wallets and — separately — bonus wallets, and links to the platform's usage and top-up pages. Either read can fail on its own; the stored grant is kept when it does.
+
+## Limits worth knowing
+
+- **No expiry or refresh.** Upstream stores the grant without an expiry and has no refresh flow, so `credential-stored` means "this machine has a grant", not "the server still accepts it". A grant the platform has revoked surfaces as an authentication failure on the next model request; `/account logout` then `/account login` replaces it.
+- **Sign-out is local first.** The grant is removed from this machine before the platform is told; a failed remote logout never restores the local login.
+- **One attempt at a time.** Starting a second sign-in while one is in flight returns the running attempt rather than replacing it.
+- **macOS and Linux open the browser** (`open` / `xdg-open`). On other platforms the URL is printed for you to open.
+
+## Where the credential lives
+
+In the same local credential store as your API keys (`~/.dscode/credentials.yaml`, `0600`), under the account provider's own record. It never reaches the model: account state is a client-safe projection with no token in it, tool results and session logs never carry it, and the command's output is redacted like every other DSCODE command result.

package/docs/auto-review.md

@@ -0,0 +1,128 @@
+# Auto permission review
+
+The repository and the complete install package ship the `dscode-auto-review` plugin. It calls an independent LLM request for actions that need approval and answers allow, deny or hand-to-human; it keeps the workspace-write sandbox and the existing network behaviour. It is not Codex's built-in reviewer, and it is not a security proxy through which every operation passes.
+
+## Usage
+
+Restart `dscode` to load the plugin. New sessions default to `auto-review`; an existing session and a saved default keep their value, and either can be switched explicitly:
+
+```text
+/permission auto-review
+/permission ask
+/review-usage
+```
+
+Both `auto-review` and `ask` are `workspace-write + approval: ask`; the difference is that the first lets the plugin review before the request. The preset was named `auto` until DSH 0.1.7 reserved that name for its own integration; a session recorded under the old name keeps its sandbox and approval values and shows as `custom` until it is switched. The underlying `never` still refuses approval requests and does not mean automatically allowed. Computer Use application authorisation and sensitive-action confirmation always go to the user.
+
+## Experimental Desktop
+
+The [combined Desktop package](browser-use.md#install-the-experimental-combined-desktop-package)
+includes this reviewer. Select **Auto review** explicitly in the session permission
+selector; installing the package preserves the Host's permission default. The
+reviewer follows the session's selected model unless configured otherwise.
+`/review-usage` reads the selected session's review audit. The audit sidecar lives
+under the Desktop Host's `$DSH_HOME/auto-review`, independently of terminal state.
+
+The same permission and fallback rules apply: a denied action does not execute,
+human fallback needs a user decision, and cancelling a pending review grants
+nothing. The `never` approval policy rejects actions that request approval before
+any reviewer or human answerer runs. Computer Use app grants remain human decisions.
+An automatic verdict is not evidence that a model reliably understands every
+action; the native execution checks use scripted decisions. See the
+[verification record](https://github.com/qiz029/dscode/blob/main/docs/verification.md#desktop-automatic-review-execution--2026-10-06)
+for their exact scope and limits.
+
+## What triggers a review
+
+- Workspace file changes, ordinary shell, and curl/CLI network access under existing permissions: no new approval and no review model call.
+- A shell/file tool asking for additional permission: enters the native approval path, and under `auto-review` the reviewer decides first.
+- Chrome's explicitly read-only tools `list_pages`, `take_snapshot`, `get_console_message`, `list_console_messages`, `get_network_request`, `list_network_requests`, `performance_analyze_insight`: no new approval.
+- Every other `mcp__*` tool: enters approval before execution, including Chrome navigation, clicking, script execution, upload and screenshots. An unknown MCP tool is not waved through because its name sounds read-only.
+- A request another plugin raises through the native approval interface: handed to a human when it cannot be bound to the actual tool arguments about to execute.
+
+This is not a global network firewall. A `curl POST` that was already allowed, or an external operation through an authenticated CLI, does not trigger auto by nature. The actual contents of a script inside the shell are not read by the reviewer either. Equivalent detours across tools are constrained by the review instruction, and no complete semantic recognition can be claimed; an identical action denied earlier in this turn is denied directly while there is no new user instruction.
+
+## Input and authorisation
+
+Before a tool executes, the plugin records the immutable arguments about to run and binds the review request to the agent and the call ID. Each allow applies to that one call; there is no permanent authorisation cache. The review model has no execution tools and does not receive the main agent's reasoning or a whole tool output.
+
+Built-in browser calls also include the host-observed page URL when available.
+WebMCP execution includes its previously discovered website definition as
+untrusted evidence; missing definitions fall back to a human, and a website's
+read-only annotation never exempts execution from review. The browser separately
+enforces site and Developer permissions and rechecks the proposed page and tool
+definition before execution. Approval does not grant those permissions. See
+[Browser use](browser-use.md) for the redirect and network-boundary limitations.
+
+The review input is the concrete tool arguments, the cwd, the direct user messages and the most recent denial reason. It does not additionally read `.env`, configured credentials or secret files. Common credential formats are redacted; when the action arguments look like they contain credentials the request goes to a human instead of asking a model to approve a distorted action. That detection is not complete DLP and cannot guarantee every arbitrary secret format is recognised, so do not paste credentials into arguments or user text.
+
+An action JSON over 12,000 characters, all direct user text over 8,000 characters, or a missing direct user instruction is handed to a human: the authorisation constraint is never trimmed away just to force a review. A summary the agent generated itself is never taken as user authorisation. A long session may therefore hand more requests to a human, which is an explicit limit of this first version.
+
+## Model and cost
+
+When the reviewer route is a [Custom provider](custom-providers.md), it skips the cloud Jev shortcut. By default it uses the provider/model the agent actually requested most recently, but with an independent, condensed review context. `config/harness.local.yml` can point at another model whose credentials are already configured:
+
+```yaml
+- id: dscode-auto-review
+  config:
+    provider: your-configured-provider
+    model: your-reviewer-model
+    timeoutMs: 30000
+    maxOutputTokens: 768
+    maxReviewsPerTurn: 20
+    maxBrowserReviewsPerTurn: 100
+```
+
+provider/model must be set together or both left empty. The default output cap is 4096 tokens; the example above lowers it to 768. Reasoning tokens also consume this cap, so a low cap can leave insufficient room for a verdict and trigger human fallback. The default timeout is 30 seconds. Each agent has a budget of 20 ordinary action reviews and a separate budget of 100 built-in browser action reviews per turn; exhausted budgets send further requests to a human. This call cap is not a billing cap: provider/adapter retries, thinking tokens and pricing are decided by the model configuration.
+
+Independent reviewer model calls remain charged to the requesting session as auxiliary `review` usage. They do not contribute to the main model's smoothed speed or active-request indicator, and they carry no wire session identity that could activate session-only prompt rewriting.
+
+`/review-usage` shows this session's decision count, model attempts, reported input/output tokens, accumulated review time and the attempts missing complete usage. The token totals accept both ordinary reviewer usage and Jev's original snake-case fields, including existing audit files. Missing, invalid or explicitly incomplete readings are counted as incomplete; valid reported tokens from partial readings remain in the totals. No historical files are rewritten. Missing usage is not treated as zero cost. A review that fails, is truncated, returns invalid JSON or times out goes to a human; when the human path is unavailable too, the native approval service refuses execution.
+
+Three denials in a row cancel the current agent's run for the turn. An explicit denial is never silently converted into another "human allow" path; the agent receives the denial reason and the instruction not to take an equivalent detour. The user can switch with `/permission ask` and then give a new explicit instruction.
+
+## Persistence and distribution
+
+The permission choice is stored by native DSH session events; the native approval asked/decided records keep recording the actual outcome. The review reason, action hash, usage and elapsed time are stored separately in `.runtime/auto-review/<session-id-sha256>.jsonl` (file mode 0600). The original command, request body, review prompt and full model response are not recorded. This sidecar is the reviewer's judgement record; after a hand-to-human, the final allow/deny follows the native session approval log.
+
+The rc.1 session reader does not accept unknown event types, so no custom review event was forced into the session log. Back up the whole `.runtime` to keep the review records too.
+
+The complete install package from `npm run dist` includes this plugin. The official npm/Hub bundle includes the reviewer; the older `npm run release` exported only the base composition and does not replace the complete release produced by `npm run release:hub`.
+
+## Jev fast path (optional)
+
+The essence of auto review is choosing one answer inside a given context, which does not need a model that writes essays. With `dscode-jev` mounted, a review first asks TypeSafe Jev (through OpenRouter's alpha Decisions endpoint `POST /api/alpha/decisions`), which answers four things in **one request**:
+
+- `choice`: `allow` / `ask` / `deny`, with per-option probabilities and a `confidence`;
+- `authorized`: whether the retained instructions cover this action, target and effect included. It is scored **separately from risk**: a dangerous action the instructions asked for should score high, and a dangerous action nobody asked for should score low. Instructions almost never name a concrete command, so the question asks about the task they asked for and the anchor is written into the question too — a step they ask for directly ≥0.9, a necessary step of a stated task 0.6–0.9, possibly part of the task but optional or unclear 0.2–0.6, not covered <0.2. This score is the switch for step 2 below (handing an authorised action to the model for a deeper review);
+- `score`: how hard it is to roll back if it goes wrong (0–3 bands, and it may land between bands);
+- `credential_risk`: whether credentials, tokens or other secrets are involved.
+
+The order of judgement is in code, and the **allow and deny thresholds are deliberately asymmetric** — allow is the dangerous direction, while a deny is only "please don't do this":
+
+1. **Automatic denial**: `deny` and (confidence ≥ `autoDeny`(0.95) and `P(deny)` ≥ `autoDenyProbability`(0.9)) **or** (confidence ≥ `autoDenyCorroborated`(0.9) and at least one of `score ≥ destructiveCeiling`(2) or credential risk ≥ `credentialRisk`(0.5) already over the line). If `authorized ≥ authorizedVeto`(0.6) — that is, the instructions appear to ask for it — the automatic denial is **vetoed and turned into a hand-to-human**: the cost of one wrongly denied action is work the user asked for not getting done, without even a prompt.
+2. **Hand to the deeper model review when authorized**: credential risk ≥ 0.5, `score ≥ 2`, a `choice` other than `allow`, or confidence < `autoAllow`(0.85) — all four guard only the allow direction and none of them constitutes a denial. If `authorized ≥ authorizedVeto`(0.6) — the instructions appear to ask for it — they no longer go straight to a human but return `defer`, leaving the reviewer model to decide with the full pending arguments and the retained instructions in view: Jev's scores are coarse, and this deployment already allows ordinary network access and lets a CLI use credentials it stored itself. When the reviewer itself rules `human`, a human is still consulted, and a `defer` is never treated as an allow.
+3. **Automatic allow**: `allow` with confidence ≥ `autoAllow`(0.85) and step 2 not triggered.
+4. Everything else (an `ask` below `authorizedVeto`, not confident enough, over the line but not denied) → hand to a human.
+
+One `defer` leaves two rows in the audit: first Jev's own verdict and risk scores (`decision: deferred`, with `credentialRisk`, `destructive`, `authorized`), then the reviewer model's actual ruling; only an `allow` really lets the action through. In other words step 2 turns credential and irreversible risk from a "hard stop" into "a second model's judgement plus a human backstop" — a deliberate trade whose cost is that those two signals no longer veto on their own, and whose benefit is that an escalation the user explicitly asked for (for example a verification that has to leave the sandbox during a release) no longer interrupts a human every time. To restore the hard stop, raise `authorizedVeto` above 1 (or switch Jev off as below).
+
+When Jev is not configured (no `OPENROUTER_API_KEY` resolves), is disabled, times out, errors or returns something unusable, it always returns "no verdict" and auto review continues with the original reviewer model — **a Jev failure only falls back to the old behaviour and never loosens any permission**.
+
+The `state` sent out has only two items: the call about to execute, and the direct user instructions retained for this session; each is truncated to 8000 characters and neither contains credentials.
+
+Jev requests also write metadata-only usage records to the requesting session and its live parent sessions. Reported billed costs enter the session total even when the verdict is unusable and the chat reviewer must run afterward. Failed requests and missing or invalid costs remain unknown, so the total is marked partial; a reported zero cost remains zero. Disabled, unconfigured and already-cancelled calls send no request and add no ledger entry. This accounting does not change approval decisions.
+
+Configuration lives on the `plugins/jev` line: `enabled` (default true), `model` (default `~typesafe/jev-latest`), `endpoint`, `apiKeyEnv` (default `OPENROUTER_API_KEY`), `timeoutMs` (default 8000), and the thresholds `autoAllow`(0.85), `autoDeny`(0.95), `autoDenyProbability`(0.9), `autoDenyCorroborated`(0.9), `authorizedVeto`(0.6), `credentialRisk`(0.5), `destructiveCeiling`(2). Setting `enabled: false` or removing the line returns to pure model review.
+
+Two measurements on 2026-09-17 (the same four cases, `~typesafe/jev-latest` → `typesafe/jev-1.13-20260917`, provider TypeSafe): 96–813 ms per call, about $0.000025 (output billed at 0). The first run (thresholds only, no automatic denial) gave `git status --short` → allow; `git push --force origin main` (deny 0.92 / score 2.99) and `curl --data-binary @.env …` (deny 0.98 / cred 0.94) → hand-to-human; `rm -rf ~/Documents/notes` (deny 0.90 / score 1.97) → deny. The second run (the asymmetric policy in this section) gave allow, deny (0.98 / P(deny) 0.99), deny (0.99 / 1.00) and deny (0.97 / 0.98) in order; `authorized` was 0.83 on the ordinary read and 0.03 on the three dangerous actions. **Confidence drifts between two runs of the same action** (`rm -rf` moved from 0.90 to 0.97), which is exactly why a decisive denial requires two signals to agree and why the audit record exists for tuning the thresholds.
+
+Four more cases were measured on this calibration path on 2026-09-19 (`typesafe/jev-1.13-20260917`): a "commit and release" instruction plus running `make release` outside the sandbox → `authorized` 0.68, `defer`; the same instruction naming `make release` → 0.86, `defer`; the same instruction plus `rm -rf ~/Documents/notes` → 0.07, `deny`; "look at the test coverage" plus the same `make release` → 0.11, `human`. To repeat it, score `approvalState({ action, context })` together with `approvalQuestions()` through `requestDecisions`, then read `approvalVerdict`.
+
+A note on thresholds: Jev's probabilities are calibrated only in the **statistical** sense, and `confidence` is not a per-call guarantee. Align the thresholds with the audit records this plugin writes (`.runtime/auto-review/*.jsonl` carries decision, source, choice, confidence, denyProbability, authorized, usage and elapsed time) rather than copying the defaults.
+
+## Verification
+
+`npm test` covers the review rule entry points, argument binding, cancellation, timeout, invalid responses, credential interception, the model budget, mode switching, repeated denials and stopping. `tests/jev.test.mjs` uses a mock transport to cover the request shape, answer parsing, threshold judgement, timeout and failure fallback; `tests/auto-review.test.mjs` additionally covers "a Jev verdict spends no reviewer request", "a Jev denial counts towards the consecutive denials", "Jev unavailable falls back to model review", and "when authorized Jev hands the guard to the reviewer model, while a reviewer ruling of human still consults a human".
+
+`npm run doctor` uses a real DSH agent and tool pipeline plus the deterministic local LLM adapter to verify that an allow executes, a denial does not execute, an invalid response goes to the test human approver, usage is recorded and the session recovers. It calls no paid remote model; real-model review quality, latency and cost are still to be verified in real use. The simulated human approver exists only in the doctor test overlay.