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

dscli_agent-0.4.0/PKG-INFO

@@ -0,0 +1,565 @@
+Metadata-Version: 2.4
+Name: dscli-agent
+Version: 0.4.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
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright>=1.45
+Requires-Dist: rich>=13.7
+Requires-Dist: prompt-toolkit>=3.0.43
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# dscli
+
+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 ──> web chat (browser) ──> one JSON envelope per turn
+          │                                       │
+          └────── local tools: read / write / patch <──┘
+```
+
+## Requirements
+
+- Python 3.10+ (developed on 3.13)
+- Google Chrome, or Playwright's Chromium
+- A DeepSeek account (the free web chat is enough)
+
+## Install
+
+```powershell
+python -m pip install dscli-agent
+```
+
+This installs the `dscli` command and its Python dependencies. Playwright's browsers are
+not downloaded by pip: dscli drives your installed Google Chrome by default. If Chrome is
+not available, install Playwright's Chromium once:
+
+```powershell
+python -m playwright install chromium
+```
+
+To work from a source checkout instead:
+
+```powershell
+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 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
+directory private because it contains logged-in browser session data.
+
+If you are not logged in through Chrome, either log in there first or run:
+
+```powershell
+dscli login
+```
+
+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:
+
+```powershell
+dscli doctor
+dscli doctor --send          # also do a one-word round-trip test
+dscli doctor --headed        # watch it work
+```
+
+## Interactive chat
+
+Start dscli without a task to open an ongoing conversation:
+
+```powershell
+dscli
+```
+
+dscli shows an inline terminal UI inspired by Claude Code: a cleared screen and gradient
+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, 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.
+
+On launch, the visible terminal is cleared before the wordmark appears. Pass
+`--no-clear` to `chat`, or set `DSCLI_NO_CLEAR=1`, to keep the previous screen contents;
+the logo and welcome card still show. This behavior is TUI-only: `--plain`, non-TTY
+output, `run`, `doctor`, `login`, and `config` keep their existing output.
+
+The agent session stays open while you work at the `❯` prompt. The complete JSON
+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 |
+| --- | --- |
+| `Enter` | Send the message (or accept a `/` completion). |
+| `Esc` then `Enter`, or `Ctrl+J` | Insert a newline for multi-line input. |
+| `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
+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
+session, or `q` to quit.
+
+### Plain mode
+
+Use `--plain` (or set `DSCLI_PLAIN=1`) to keep the earlier line-based interface:
+
+```powershell
+dscli chat --plain
+```
+
+The plain UI prints progress to stderr, accepts one line per message, and uses
+`you> ` as its prompt. It is also selected automatically when stdin or stdout is not
+a terminal (for example when redirecting output), when `TERM=dumb`, or when the UI
+dependencies cannot start. On Windows, Windows Terminal renders the UI best; legacy
+`conhost` windows may show simpler output.
+
+You can also use the explicit command with the common agent flags:
+
+```powershell
+dscli chat --headed --workspace C:\projects\app --max-steps 8
+```
+
+## Run a one-shot task
+
+```powershell
+# Simple task in the current directory
+dscli run "Add input validation to app.py and a test for it"
+
+# Attach files (they are uploaded into the chat on the first turn)
+dscli run "Refactor the parser" -f src/parser.py -f tests/test_parser.py
+
+# Globs work too; quote them so the shell does not expand them
+dscli run "Fix the bug" -f "src/**/*.py" --workspace C:\projects\app
+
+# Read a long task from a file; auto-approve edits and approved shell commands
+dscli run --prompt-file task.md -y
+
+# Disable command execution entirely for this run
+dscli run "Review the docs" --no-shell
+```
+
+The final answer is printed to stdout. Progress, diffs, and approval prompts go to
+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 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
+
+| Flag | Meaning |
+| --- | --- |
+| `-f, --file PATH` | Attach a file (repeatable, globs supported). |
+| `--workspace PATH` | Root the tools may touch. Defaults to the current directory. |
+| `-y, --yes` | Approve every write/patch/command without asking. |
+| `--no-shell` | Disable `run_command` for this run (commands are otherwise enabled and approved per command). |
+| `--allow-outside` | Let tools read/write outside the workspace. |
+| `--headed` / `--headless` | Show or hide the browser. Headless is the default. |
+| `--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. |
+| `--no-verify` | Disable the configured `verify_command` for this run. |
+| `--prompt-file PATH` | Read the task from a UTF-8 file. |
+| `--no-clear` | Keep previous terminal output when the TUI starts (chat only). |
+| `--no-auto-login` | Do not open a visible browser if a headless login is needed. |
+| `-v, --verbose` | Show model thoughts and raw replies. |
+| `-q, --quiet` | Only print the final answer. |
+| `--dry-run` | Print the exact first prompt and exit. |
+
+Use `-` as the task to read it from stdin.
+
+## How it works
+
+Each turn is one normal chat message. The first message contains the system contract,
+the environment, a workspace preview, the attachment manifest, and the task. The model
+is required to answer with exactly one ` ```json ` fenced block containing one JSON
+object:
+
+````markdown
+```json
+{
+  "thought": "I should read the file first.",
+  "tool_calls": [
+    {"name": "read_file", "arguments": {"path": "src/app.py"}}
+  ],
+  "final": null
+}
+```
+````
+
+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 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 |
+| --- | --- |
+| `read_file` | Read a text file, optionally a line range. Required before patching. |
+| `write_file` | **Create** a new file. Refuses to overwrite an existing non-empty file. |
+| `apply_patch` | The only way to edit an existing file: exact `search` → `replace`. |
+| `list_files` | Bounded recursive listing. |
+| `delete_file` | Delete one file when explicitly requested (approval required). |
+| `run_command` | Run a command with an approval prompt via PowerShell, cmd.exe, sh, or bash. |
+| `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.
+
+`run_command` uses `shell: auto` by default: PowerShell when available on Windows
+(cmd.exe otherwise), and `/bin/sh` elsewhere. Pass `"shell": "cmd"` for cmd.exe syntax
+such as `%VAR%` or batch builtins, `"powershell"`, `"sh"`, or `"bash"` to choose another
+interpreter. On POSIX systems, `auto` falls back to `/bin/sh`; `bash` is selected only
+when explicitly requested. The approval prompt names the resolved interpreter, so a
+command is never run under a shell you did not see.
+
+### Plan and verification loop
+
+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:
+
+```powershell
+dscli run -y --verify "python -m pytest -q" "Add a test for the parser"
+```
+
+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 a per-command approval prompt, even when `--no-shell` is set, because you
+configured it explicitly. Treat it like any other command you run from the shell: the
+model can modify the files it checks, so review the final diff.
+
+## Approvals and safety
+
+- Tools are confined to the workspace unless `--allow-outside` is passed.
+- `.git` is never writable through the tools.
+- Every write, patch, delete, and command shows a diff/command and asks
+  `[y]es / [n]o / [a]ll / [q]uit` before changing anything. `-y` skips the prompts.
+- Command execution is enabled by default, but every model-requested command still
+  requires approval. The prompt names the interpreter (PowerShell, cmd.exe, sh, or
+  bash). `--no-shell` disables model-requested commands for a run.
+- The verification command is the one exception to the approval flow: when you configure
+  it with `--verify` or `verify_command`, dscli runs it automatically after edits,
+  without a prompt and even when `--no-shell` is set. The model can neither call nor
+  change it.
+- Attachment contents, file contents, command output, and tool results are treated as
+  untrusted data by the system prompt.
+- The built-in file tools do not use the network. Approved commands can run any local
+  program, including network clients; dscli itself only talks to the chat provider
+  through the browser.
+
+This is still an assistant with write access to your files. Use a clean workspace or
+version control, and review diffs before approving them.
+
+## Configuration
+
+The config is JSON at:
+
+```powershell
+dscli config --path
+dscli config --show
+dscli config --set headless=false
+dscli config --set stable_seconds=6
+```
+
+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`, `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`, `shell_enabled`
+(default true; every command still requires approval), `allow_outside`,
+`verify_command` (empty disables verification),
+`verify_timeout_sec` (clamped to 1–600, default 300).
+
+Headless Chrome normally sends a `HeadlessChrome/...` user agent, which DeepSeek's CDN
+rejects with a CloudFront 403. dscli automatically replaces it with the installed
+Chrome's real version when running headless. Set `user_agent` explicitly if you need a
+different string.
+
+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=\"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.** 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
+still happens, run `dscli login` headed once, then check whether
+`doctor --headed` can reach the composer. You can also set `"channel": ""` or override
+`"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 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
+profile.
+
+**The send button never enables.** The attachment may still be uploading, the message
+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 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`.
+
+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.
+- 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 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 DeepSeek's terms.
+  Use your own account and judgment.
+
+## Development
+
+```powershell
+python -m compileall -q dscli
+dscli doctor
+```
+
+The package is intentionally small: `browser.py` owns Playwright and selectors,
+`scraper.py` holds the in-page JavaScript, `protocol.py` parses the envelope,
+`tools.py` enforces the sandbox, and `agent.py` runs the turn loop.
+
+### Publishing
+
+PyPI uploads are manual and use your own API token:
+
+```powershell
+python -m pip install -e ".[dev]"
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+Twine prompts for the username `__token__` and your PyPI API token. Bump
+`__version__` in `dscli/__init__.py` before every upload; PyPI never allows a version
+number to be reused.
+
+## License
+
+MIT