dscli-agent 0.2.0__tar.gz → 0.3.0__tar.gz

{dscli_agent-0.2.0 → dscli_agent-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dscli-agent
-Version: 0.2.0
-Summary: A local coding agent that uses the DeepSeek web chat UI as its model
+Version: 0.3.0
+Summary: A local coding agent that uses DeepSeek web chat as its model
 Author: Anish
 License-Expression: MIT
 Keywords: cli,coding-agent,deepseek,playwright,terminal,ai
@@ -30,13 +30,13 @@ Dynamic: license-file
 
 # dscli
 
-A local coding agent that uses the **DeepSeek web chat UI** as its model. No API key:
-dscli drives a real browser session, sends prompts to `https://chat.deepseek.com/`, reads
-the replies, and executes file-editing tools on your machine.
+A local coding agent that uses a **web chat UI** as its model. No API key: dscli drives
+a real browser session, sends prompts to DeepSeek's chat page, reads the replies, and
+executes file-editing tools on your machine.
 
 ```
-you ──> dscli ──> DeepSeek chat (browser) ──> one JSON envelope per turn
-          │                                            │
+you ──> dscli ──> web chat (browser) ──> one JSON envelope per turn
+          │                                       │
           └────── local tools: read / write / patch <──┘
 ```
 
@@ -69,10 +69,11 @@ python -m pip install -e ".[dev]"
 ## Sign-in
 
 If you already use DeepSeek in Chrome, dscli reuses that saved session automatically,
-even while Chrome is open. It reads DeepSeek's saved login token from Chrome's local
-storage and seeds its own isolated browser profile; Chrome's cookies are copied too when
-they are available. Your normal Chrome profile is never controlled by the automation,
-and you do not need to quit Chrome or sign in again.
+even while Chrome is open. It reads DeepSeek's login token from Chrome's local storage
+on every start and overwrites any stale copy left in dscli's profile, so the session in
+Chrome always wins. Chrome's cookies are copied as well whenever Chrome is not holding
+its cookie database open. Your normal Chrome profile is never controlled by the
+automation, and you do not need to quit Chrome or sign in again.
 
 The isolated profile is persistent and lives under `%APPDATA%\dscli\profile` on Windows
 (`~/Library/Application Support/dscli` on macOS, `~/.config/dscli` elsewhere). Keep this
@@ -84,8 +85,8 @@ If you are not logged in through Chrome, either log in there first or run:
 dscli login
 ```
 
-A visible browser window opens for a manual DeepSeek login, including any Cloudflare
-check. dscli closes it as soon as the chat composer appears.
+A visible browser window opens for a manual sign-in, including any Cloudflare check.
+dscli closes it as soon as the chat composer appears.
 
 Check the page and selectors without sending anything:
 
@@ -107,8 +108,12 @@ dscli shows an inline terminal UI inspired by Claude Code: a cleared screen and
 ASCII wordmark on launch, an animated spinner with rotating status verbs, a smoothly
 revealed streaming answer, compact tool cards (`⏺ Read(...)`, `⏺ Update(...)`,
 `⏺ Run(...)`), colored diffs for approvals, and the final answer rendered as Markdown.
+Accents use a muted palette that matches the wordmark: sage for success, dusty rose for
+errors, and soft teal for diffs and highlights. The same muted colors apply to the
+plain and non-TTY output.
 Output stays in normal scrollback after startup; dscli does not take over the full
-screen, and the welcome card shows the workspace, active modes, and shortcuts. Plans
+screen, and the welcome card shows the workspace, model, active modes, and shortcuts.
+Plans
 render as a compact checklist, and a configured verification command appears as a
 `Verify` card after file edits. `dscli chat --verify CMD` applies the check to each
 message.
@@ -123,6 +128,77 @@ envelope is still parsed and validated before any tool runs. File approvals,
 auto-approval state, and workspace context remain active across messages.
 `--max-steps` applies separately to each message.
 
+DeepThink is always enabled, and the UI streams the model's reasoning live in a
+compact block above the reply:
+
+```text
+  Thinking
+  │ I should inspect the configuration first.
+  │ … +12 rows (Ctrl+O)
+  │ charlie line
+  │ delta line
+  │ echo line
+```
+
+The first sentence stays pinned at the top while the newest three wrapped rows
+autoscroll beneath it, with the collapsed row count in between. Text is revealed
+between provider polls so the block keeps streaming in real time. When the turn ends
+it collapses to the same limited view with a `Ctrl+O` hint; press `Ctrl+O` at the
+prompt to print the full reasoning block (up to 500 rows) into the transcript.
+The streamed block is TUI-only; `--plain` and `run` do not show it.
+
+The prompt footer tracks session token usage against a 1,000,000-token budget, and the
+same progress bar renders below the live Thinking and Responding output:
+
+```text
+  tokens ███████░░░░░ 612.4k / 1.0M · 61%
+```
+
+Counts are estimated locally from every prompt sent and reply received (one token per
+CJK character, about four characters per token otherwise); they are not reported by
+DeepSeek. Attachment contents are not included. The count resets on `/new` and whenever
+a new chat is opened.
+
+### Conversation compaction
+
+When the estimate reaches 1,000,000 tokens, dscli compacts the session instead of
+stopping. Before the next prompt is sent it asks the current chat to write a structured
+compaction summary — an `<analysis>` pass followed by a `<summary>` covering the request,
+technical decisions, files and code, errors and fixes, user messages, pending tasks, and
+the next step, following the same compact guide Claude Code uses. It then writes the
+conversation to a text file, starts a new DeepSeek chat, and sends a resume prompt that
+embeds the compaction and attaches the file. If the summary request fails or returns
+nothing usable, the deterministic activity log is used on its own. The compaction
+contains the model summary (when available), the conversation resume, the current task,
+the remaining (unfinished) plan steps, files changed so far, the verification state,
+the project structure, and instructions for continuing, so the model keeps working
+without redoing finished work.
+
+Files are saved under `%APPDATA%\dscli\compactions` on Windows
+(`~/Library/Application Support/dscli/compactions` on macOS,
+`~/.config/dscli/compactions` elsewhere) as `compaction-YYYYmmdd-HHMMSS.txt`. The check
+runs before every model turn, so it also works mid-task; the TUI shows a
+`Compacting conversation` spinner while the summary is written, then a
+`⟳ Compacted 1.0M tokens → … · new chat` notice. `/new` clears the recorded
+conversation as well.
+
+### Deeplanning mode
+
+```powershell
+dscli run "Split the parser module" --deeplanning
+dscli chat --deeplanning
+```
+
+Deeplanning makes the model plan before it acts. While the run has no plan, the harness
+refuses `write_file`, `apply_patch`, `delete_file`, and `run_command` with an error result
+that tells the model to plan first. `read_file` and `list_files` stay available so the
+model can investigate, and `update_plan` unlocks execution as soon as it records a
+non-empty plan. The gate is enforced by dscli, not just requested in the prompt, so a
+model that skips the plan cannot touch the workspace. Plans remain per message: each new
+chat message needs its own plan, and clearing the plan re-arms the gate. Enable it for
+every run with `dscli config --set deeplanning=true`, or turn it off for one run with
+`--no-deeplanning`.
+
 ### Prompt shortcuts
 
 | Key | Action |
@@ -132,6 +208,7 @@ auto-approval state, and workspace context remain active across messages.
 | `Ctrl+C` | While the agent is working: interrupt the current turn, keep the browser session, and return to the prompt. At the prompt: clear the input. |
 | `Ctrl+D` | Exit dscli. |
 | `↑` / `↓` | Browse previous messages. |
+| `Ctrl+O` | Expand the last thinking block in full. |
 
 Typing `/` opens an autocomplete menu. History is saved to
 `%APPDATA%\dscli\chat_history` (`~/Library/Application Support/dscli/chat_history` on
@@ -140,6 +217,14 @@ macOS, `~/.config/dscli/chat_history` elsewhere).
 Slash commands: `/help` lists commands and shortcuts, `/new` starts a fresh
 conversation so the agent forgets earlier turns, and `/exit` (or `/quit`) closes dscli.
 
+If Cloudflare interrupts a headless run, dscli opens the persistent profile in a visible
+Chrome window and resubmits the interrupted prompt. Complete the check in that window.
+dscli keeps the window open until the response actually starts, then minimizes it, keeps
+working, and closes the window and returns to headless when the task finishes. The
+current model turn restarts with the same prompt in a fresh chat, so an answer that was
+already streaming when the check appeared is fetched again. Set
+`dscli config --set auto_human_check=false` to fail fast instead.
+
 When dscli asks to write a file or run a command, it shows the title and a compact
 colored diff (additions green, deletions red, hunks cyan) even when `-y` is active.
 Answer `y` to approve once, `n` to deny, `a` to approve everything for the rest of the
@@ -185,9 +270,9 @@ The final answer is printed to stdout. Progress, diffs, and approval prompts go
 stderr, so `dscli run ... > result.txt` captures only the answer. `run` never uses the
 interactive UI; its output contract is unchanged.
 
-Exit codes: `0` success, `1` error, `2` model-turn budget exhausted, and `3`
-verification failed (takes precedence over `2`). Verification failures are always
-logged to stderr, including under `-q`.
+Exit codes: `0` success, `1` error, `2` model-turn budget exhausted or the result was not
+confirmed complete, and `3` verification failed (takes precedence over `2`). Verification
+failures and unconfirmed completions are always logged to stderr, including under `-q`.
 
 ### Common flags
 
@@ -199,7 +284,8 @@ logged to stderr, including under `-q`.
 | `--allow-shell` | Enable `run_command` (still approved per command). |
 | `--allow-outside` | Let tools read/write outside the workspace. |
 | `--headed` / `--headless` | Show or hide the browser. Headless is the default. |
-| `--deepthink` / `--search` | Turn DeepSeek's modes on for the run. |
+| `--search` | Turn DeepSeek's Search mode on for the run (DeepThink is always on). |
+| `--deeplanning` | Require a non-empty `update_plan` before writes or commands (alias: `--deep-planning`). |
 | `--max-steps N` | Maximum model turns (default 12). |
 | `--timeout N` | Response timeout per turn in seconds (default 300). |
 | `--verify CMD` | Run CMD automatically after file edits; failures block success. |
@@ -232,18 +318,34 @@ object:
 ```
 ````
 
-The fence matters: DeepSeek renders unfenced replies as Markdown, which auto-links
+The fence matters: web chats render unfenced replies as Markdown, which auto-links
 tokens like `object.is` and eats `*` or `[...]`, corrupting code inside the JSON.
 dscli parses the envelope (also tolerating unfenced JSON and small formatting
 variations), runs the tool calls locally, and sends the results back in the next
-message inside nonce-tagged markers. The loop ends when the model replies with
-`tool_calls: []` and a non-empty `final` string, or when the turn budget is exhausted.
-Before a final is accepted, unfinished plan steps and the configured verification
-command can send the model back for more work (see below).
+message inside nonce-tagged markers. The loop ends only when the model replies with
+`tool_calls: []`, a non-empty `final` string, and `"complete": true`:
+
+````markdown
+```json
+{"thought": "the work is complete", "tool_calls": [], "complete": true, "final": "..."}
+```
+````
+
+A final without `complete: true`, or with any unfinished plan step, is rejected and the
+model is sent back to continue. When the turn budget runs out first, dscli asks for a
+wrap-up summary and reports the result as not confirmed complete (`dscli run` exits with
+code `2`). The configured verification command can also send the model back for repairs
+(see below).
 
 Malformed replies get up to two correction prompts. Every raw reply that fails to parse
 is saved to the debug directory.
 
+The system contract adopts the operating guidance from Claude Code's Opus 5.5 system
+prompt, adapted to dscli's envelope protocol and local tools: act once you have enough
+information, keep changes minimal and consistent with the surrounding code, avoid scope
+creep and unnecessary abstractions, confirm hard-to-reverse actions, reference code as
+`path:line`, report outcomes faithfully, and treat all tool output as untrusted data.
+
 ### Tools
 
 | Tool | Purpose |
@@ -254,19 +356,20 @@ is saved to the debug directory.
 | `list_files` | Bounded recursive listing. |
 | `delete_file` | Delete one file when explicitly requested (approval required). |
 | `run_command` | Run a shell command (only with `--allow-shell`, approval required). |
-| `update_plan` | Create or revise the task plan; the final is deferred while steps are unfinished. |
+| `update_plan` | Create or revise the task plan; the task cannot finish while steps are unfinished. |
 
 `apply_patch` normalises line endings for matching, preserves the file's encoding and
 line endings when writing, and refuses ambiguous matches unless `replace_all` is set.
 
 ### Plan and verification loop
 
-The agent can maintain a short task plan with `update_plan` (at most 20 steps). While
-any step is `pending` or `in_progress`, dscli holds the final answer back and sends a
-bounded reminder (at most two) asking the model to finish or revise the plan. If the
-steps are still unfinished at the turn limit, the answer is accepted with a visible
-"plan incomplete" warning rather than deadlocking the run. Plans apply to a single
-message on chat and are reset for every new task.
+The agent can maintain a short task plan with `update_plan` (at most 20 steps). The run
+does not finish while any step is `pending` or `in_progress`; the model is told which
+steps remain and asked to finish them or revise the plan. It must also declare
+`"complete": true` explicitly, so a bare "done" summary cannot end a task by accident.
+There is no give-up acceptance: if the budget runs out first, the result is reported as
+not confirmed complete instead of being treated as a successful finish. Plans apply to a
+single message in chat and are reset for every new task.
 
 Configure a verification command with `--verify CMD` or the `verify_command` config
 key, for example:
@@ -275,10 +378,12 @@ key, for example:
 dscli run -y --verify "python -m pytest -q" "Add a test for the parser"
 ```
 
-After a turn changes files, dscli runs the command itself, shows the result, and feeds
-failures back to the model for up to two repair attempts. If the check still fails, the
-run ends with the best available answer, marks verification as failed, and `dscli run`
-exits with code `3`. Verification only runs when the current message changed files.
+When the model claims completion after changing files, dscli runs the command itself,
+shows the result, and feeds failures back to the model for up to two repair attempts. If
+the check still fails, the run ends with the best available answer, marks verification as
+failed, and `dscli run` exits with code `3`. Verification only runs when the current
+message changed files. A verified result is still only as trustworthy as the command you
+configured.
 
 The verification command is supplied by you and is never a model-callable tool. It is
 run without `--allow-shell` and without a per-command approval prompt because you
@@ -314,13 +419,15 @@ dscli config --set headless=false
 dscli config --set stable_seconds=6
 ```
 
-Useful keys: `headless`, `channel` (`chrome`, `msedge`, or empty for Playwright's
-Chromium), `chrome_user_data_dir` (Chrome's user-data directory; empty disables Chrome
-session import), `chrome_profile` (empty = Chrome's last-used profile, or a name such as
+Useful keys: `url` (the DeepSeek chat URL; set it only for a custom deployment),
+`headless`, `channel` (`chrome`, `msedge`, or empty for Playwright's Chromium),
+`chrome_user_data_dir` (Chrome's user-data directory; empty disables Chrome session
+import), `chrome_profile` (empty = Chrome's last-used profile, or a name such as
 `Default` / `Profile 1`), `user_agent` (empty = derive a normal Chrome UA from the
 installed browser), `response_timeout_sec`, `first_response_timeout_sec`,
-`stable_seconds`, `fallback_stable_seconds`, `max_steps`, `max_tool_calls`,
-`max_read_chars`, `max_attachment_mb`, `deepthink`, `search`, `allow_shell`,
+`stable_seconds`, `fallback_stable_seconds`, `auto_human_check` (true = open a visible
+window to solve a verification check; false = fail fast), `max_steps`, `max_tool_calls`,
+`max_read_chars`, `max_attachment_mb`, `search`, `deeplanning`, `allow_shell`,
 `allow_outside`, `verify_command` (empty disables verification),
 `verify_timeout_sec` (clamped to 1–600, default 300).
 
@@ -329,24 +436,32 @@ rejects with a CloudFront 403. dscli automatically replaces it with the installe
 Chrome's real version when running headless. Set `user_agent` explicitly if you need a
 different string.
 
-If DeepSeek changes its UI, override the affected CSS selectors in the `selectors`
-object of the config file (they are merged over the defaults):
+DeepSeek's default selectors live in `dscli/providers.py`. If its UI changes, override
+the affected CSS selectors in the `selectors` object of the config file (they are merged
+over the defaults):
 
 ```json
 {
   "selectors": {
-    "composer": "textarea[placeholder=\"Message DeepSeek\"]",
-    "assistant_message": ".ds-markdown.ds-assistant-message-main-content",
-    "send_button": "div[role=\"button\"].ds-button--primary.ds-button--circle"
+    "composer": "textarea[placeholder=\"Ask anything\"]",
+    "send_button": "button.new-send"
   }
 }
 ```
 
+Selectors saved by older dscli versions that match DeepSeek's built-in defaults are
+ignored automatically, so built-in selector updates still take effect. Custom overrides
+are preserved.
+
 ## Troubleshooting
 
-**Cloudflare / human check in headless mode.** dscli stops with a clear message. Run
-`dscli login` (or `doctor --headed`) once in a visible browser, complete the
-check, and retry.
+**Cloudflare / human check in headless mode.** When a check interrupts a
+headless run, dscli opens the same persistent profile in a visible Chrome window and
+waits for you to solve it. The window stays visible until the reply starts, then
+minimizes; dscli finishes the task, then closes the window and returns to headless. If
+the window does not appear or the check times out, run `dscli login` (or
+`dscli doctor --headed`) once in a visible browser and retry. Set
+`auto_human_check` to false to keep the fail-fast behavior.
 
 **403 ERROR / "Request blocked" from CloudFront.** This is usually the headless browser
 being fingerprinted. dscli tries to avoid it by using a normal Chrome user agent. If it
@@ -355,11 +470,14 @@ still happens, run `dscli login` headed once, then check whether
 `"user_agent"` in the config.
 
 **"Not logged in" or the composer never appears.** Confirm that DeepSeek works in your
-normal Chrome browser. dscli imports the saved login even while Chrome is running; if
-that login has expired, refresh or sign in at `chat.deepseek.com` in Chrome and retry.
-If the composer still does not appear, run `dscli doctor --headed`, or
-`dscli login` to sign in directly in the isolated profile. To stop importing
-Chrome sessions, set `chrome_user_data_dir` to an empty string in the config.
+normal Chrome browser. dscli imports the saved login on
+every start, even while Chrome is running; if that login has expired, refresh or sign in
+at `chat.deepseek.com` in Chrome and retry. Chrome keeps its cookie database
+locked while it runs, so dscli keeps using the cookies already saved in its own profile
+and refreshes them from Chrome the next time it starts with Chrome closed. If the
+composer still does not appear, run `dscli doctor --headed`, or
+`dscli login` to sign in directly. To stop importing Chrome sessions,
+set `chrome_user_data_dir` to an empty string in the config.
 
 **"The dscli browser profile is already in use."** Close any other dscli/Chrome window
 that uses `%APPDATA%\dscli\profile`, then retry. Do not point two runs at the same
@@ -369,9 +487,10 @@ profile.
 may exceed the chat's limit, or the selector may have changed. Run `doctor` and check
 the reported counts.
 
-**A response is cut off around 12 s after the last text change.** DeepSeek did not show
-its "Read aloud" toolbar, so dscli used the fallback completion detector. Increase
-`fallback_stable_seconds` if replies are still streaming at that point.
+**A response is cut off around 12 s after the last text change.** DeepSeek did not
+show its completion toolbar (`Read aloud`), so dscli used the fallback completion
+detector. Increase `fallback_stable_seconds` if replies are still streaming at that
+point.
 
 **Chrome will not launch.** Set `"channel": ""` in the config to use Playwright's
 Chromium, after running `python -m playwright install chromium`.
@@ -380,20 +499,24 @@ Debug screenshots and unparsed replies are written to `%APPDATA%\dscli\debug`.
 
 ## Limitations
 
-- The DeepSeek web UI is not a stable API. Selectors, rate limits, and features can
-  change at any time; `doctor` and the configurable selectors are the escape hatch.
+- The DeepSeek web UI is not a stable API. Selectors, rate limits, and
+  features can change at any time; `doctor` and the configurable selectors are the
+  escape hatch.
 - Chat messages can be length-limited. dscli caps the initial prompt and tool output,
   and long files should be read in ranges rather than pasted.
 - Streaming is approximated by polling the DOM, not by tokens from the model. The
-  interactive chat shows the final answer as the page updates, but tool calls still
-  wait for the complete, validated JSON envelope.
-- Interrupting with Ctrl+C clicks DeepSeek's stop button when dscli can find it. If the
-  page does not expose one, generation may continue on DeepSeek's side; the interrupted
-  answer is discarded, and the next message (or `/new`) re-establishes a clean turn.
-- DeepSeek attachments accept only certain file types. When a file cannot be attached,
+  interactive chat streams a final answer as the page updates only after it declares
+  `complete: true`; tool calls still wait for the complete, validated JSON envelope.
+  The token bar is likewise a local estimate of sent and received text, not usage
+  reported by DeepSeek.
+- Interrupting with Ctrl+C clicks DeepSeek's labelled stop button when dscli can find
+  it. If the page does not expose one, generation may continue in the web chat; the
+  interrupted answer is discarded, and the next message (or `/new`) re-establishes a
+  clean turn.
+- Web-chat attachments accept only certain file types. When a file cannot be attached,
   the agent can still read it through `read_file` because the workspace path is provided
   in the prompt.
-- Using browser automation against a web chat may conflict with the provider's terms.
+- Using browser automation against a web chat may conflict with DeepSeek's terms.
   Use your own account and judgment.
 
 ## Development