devorch 0.3.0__tar.gz → 0.5.0__tar.gz

devorch-0.5.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,60 @@
+name: Bug report
+description: Something is broken or behaves unexpectedly
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting! **Remove API keys and other secrets** from anything you paste.
+        For security problems, do not open an issue: see SECURITY.md.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Run `devorch -p openai`
+        2. Type ...
+        3. See ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: DevOrch version
+      description: Output of `devorch --version` (or `pip show devorch`)
+    validations:
+      required: true
+  - type: input
+    id: provider
+    attributes:
+      label: Provider and model
+      placeholder: openai / gpt-4o
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options: [Linux, macOS, Windows, Other]
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+  - type: input
+    id: terminal
+    attributes:
+      label: Terminal
+      description: For display or input problems (e.g. iTerm2, Windows Terminal, GNOME Terminal, tmux)
+  - type: textarea
+    id: logs
+    attributes:
+      label: Output / logs
+      render: shell

devorch-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/Amanbig/DevOrch/security/advisories/new
+    about: Please report security issues privately, not as a public issue.

devorch-0.5.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Describe the use case, not just the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives you considered
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contribution
+      options:
+        - label: I'd be willing to open a pull request for this

devorch-0.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## Summary
+
+<!-- What does this change and why? Link the issue it closes (Fixes #123). -->
+
+## Changes
+
+-
+
+## How it was tested
+
+<!-- Tests added/updated, and anything you ran manually. Be explicit about what you did NOT test. -->
+
+## Checklist
+
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] `pytest` passes, with tests for new behaviour (a bug fix has a test that fails without it)
+- [ ] README / `CHANGELOG.md` updated for user-facing changes
+- [ ] No secrets, personal paths or API keys in code, tests, or logs

devorch-0.5.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

{devorch-0.3.0 → devorch-0.5.0}/.github/workflows/ci.yml

@@ -1,8 +1,6 @@
 name: CI
 
 on:
-  push:
-    branches: [main]
   pull_request:
     branches: [main]
 

devorch-0.5.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.5.0
+
+A large feature release: hooks, checkpoints, project settings, image input, streaming, prompt caching,
+cost estimates, and a much more robust terminal UI.
+
+### Upgrade notes
+- **Project hooks and some project settings now need `devorch trust`.** `.devorch/hooks.yaml`, a project's
+  `mcp_servers`, permission `allow` rules and `default_mode: auto` are ignored (with a warning) until you review the
+  files and run `devorch trust`. Editing either file revokes trust.
+- **Ctrl+C no longer quits.** It cancels the current turn; press it twice at an idle prompt (or type `exit`) to quit.
+- **`/undo` now also restores files** the agent changed with `edit` / `filesystem write` (not shell commands).
+- **The REPL clears the visible screen on start** (scrollback is kept). Set `DEVORCH_NO_CLEAR=1` to disable.
+- `devorch run --mode` now defaults to the project setting, falling back to `auto`.
+- Requires `prompt_toolkit>=3.0.28`.
+
+### Added
+- **Hooks**: `PreToolUse` / `PostToolUse` shell hooks (`~/.devorch/hooks.yaml`, `.devorch/hooks.yaml`).
+- **Checkpoints**: file snapshots per turn, restored by `/undo`; `/checkpoints` lists them.
+- **Custom slash commands** from Markdown files (`~/.devorch/commands`, `.devorch/commands`) with `$ARGUMENTS`.
+- **`@file` mentions** with line ranges, directories and tab completion.
+- **Image input**: `@screenshot.png` for vision models across providers; large images are downscaled
+  (optional `devorch[images]`) and old images are pruned from context to save tokens.
+- **`--output json` / `stream-json`** for `ask` and `run`, with usage, tool calls and cost.
+- **Structured `git` tool** (status, diff, log, show, branch, switch, add, commit); no push/reset/force.
+- **Per-project settings** (`.devorch/settings.yaml`) with a trust model.
+- **Streaming** replies for every provider.
+- **Prompt caching** for Anthropic (and `anthropic/*` via OpenRouter); tests guard prompt-prefix stability so
+  OpenAI/DeepSeek/Kimi/Gemini automatic caches keep hitting.
+- **`/cost`** and cost estimates in the per-turn line, `/tokens`, the bottom bar and JSON output; prices are
+  approximate and overridable under `pricing:` in `config.yaml`.
+- **More slash commands**, matching the CLI: `/permissions allow|deny|set|reset`, `/sessions`, `/hooks`, `/trust`,
+  `/untrust`, `/exit`.
+- **`--mode` for `devorch` / `devorch chat`, and `--dangerously-skip-permissions`** on every entry point (same as
+  `--mode auto`: no prompts; dangerous-command blocks and deny rules still apply).
+- **Input surface**: open input box with a coloured mode label, `Shift+Tab` mode cycling, `Ctrl+J` newline, a
+  width-aware placeholder and bottom bar, context-usage gauge.
+
+### Fixed
+- **Anthropic: the base system prompt was overwritten** by plan-mode / loop-advisory system messages.
+- **Tool output crashed the turn** (`MarkupError`) when a command, path, result or diff contained text like `[/x]`,
+  and silently lost brackets (`app/[id]/page.tsx`, `List[int]`). Message helpers now escape their text.
+- Reading a file that merely contained `Error:` was shown as a red failure.
+- Ctrl+C inside a sub-agent was swallowed and the parent kept running.
+- The bottom toolbar re-ran `git` on every keystroke; it is now cached.
+- The bottom toolbar rendered as a bright reversed bar, and was clipped on narrow terminals, hiding the mode.
+- Saving config no longer drops a `pricing:` section.
+- The slash-command dropdown vanished when a command was fully typed (`/cost`, `/models`).
+
+### Changed
+- CI runs on pull requests only.

devorch-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+We want DevOrch to be a friendly, welcoming project for everyone, whatever their background or experience.
+
+## Our standards
+
+Expected:
+
+- Be respectful and patient, especially with people who are new.
+- Give and accept constructive feedback; critique the work, not the person.
+- Assume good faith, and ask when something is unclear.
+- Keep discussion on topic and credit other people's work.
+
+Not acceptable:
+
+- Harassment, insults, personal attacks, or discriminatory language or jokes.
+- Trolling, deliberately derailing threads, or spamming.
+- Publishing someone else's private information.
+- Any other conduct that would reasonably be considered inappropriate in a professional setting.
+
+## Scope
+
+This applies in all project spaces (issues, pull requests, discussions, commits) and when someone is
+representing the project in public.
+
+## Enforcement
+
+Maintainers may edit or remove comments, close or lock threads, and ban people who do not follow these
+standards. To report a problem privately, contact the maintainer at the address listed in the `authors`
+field of `pyproject.toml`. Reports are treated confidentially.
+
+This policy is inspired by the [Contributor Covenant](https://www.contributor-covenant.org).

devorch-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing to DevOrch
+
+Thanks for helping out! DevOrch is a multi-provider AI coding assistant CLI, and contributions of all sizes
+are welcome: bug reports, docs, tests, new providers, tools and features.
+
+By participating you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). To report a security problem,
+see [SECURITY.md](SECURITY.md) instead of opening a public issue.
+
+## Getting set up
+
+```bash
+git clone https://github.com/Amanbig/DevOrch.git
+cd DevOrch
+python -m venv .venv && source .venv/bin/activate      # or: uv venv && source .venv/bin/activate
+pip install -e ".[dev]"                                 # or: uv pip install -e ".[dev]"
+
+pytest                  # the whole suite; no network or API keys needed
+ruff check .            # lint
+ruff format .           # format (CI runs `ruff format --check .`)
+devorch                 # run your working copy
+```
+
+Python 3.10+ is required; CI runs the tests on Linux, macOS and Windows for 3.10-3.13, so avoid
+platform-specific assumptions (paths, shells, terminal behaviour) and keep type hints 3.10-compatible.
+
+## Workflow
+
+1. Open an issue first for anything large, so we can agree on the approach.
+2. Create a branch per change (`feat/...`, `fix/...`, `docs/...`, `chore/...`).
+3. Keep PRs focused: one feature or fix per PR.
+4. Use clear, conventional-style commit messages (`feat(hooks): ...`, `fix(ui): ...`).
+5. Open a PR against `main`. CI must pass (lint + tests on all platforms).
+
+A good PR includes:
+
+- **Tests** for new behaviour and for the bug it fixes. A regression test should fail without your fix.
+- **Docs**: update the README for user-facing changes and add a line to `CHANGELOG.md`.
+- An honest description: what changed, why, what you did **not** test.
+
+## Where things live
+
+See [`DEVORCH.md`](DEVORCH.md) and the project structure in the README. In short: `cli/` (commands, REPL, UI),
+`core/` (agent loop, executor, hooks, memory, sessions), `providers/` (one file per LLM provider), `tools/`
+(built-in tools), `config/` (settings, permissions, project settings), `tests/`.
+
+### Adding a provider
+
+Subclass `LLMProvider` in `providers/<name>.py`, implement `generate()`, and register it in
+`providers/__init__.py`. Set the capability flags honestly: `supports_images` and `supports_streaming`
+(`generate()` then accepts `on_text` and streams deltas). OpenAI-compatible APIs can reuse `chat_create` /
+`post_chat` and `openai_user_content` from `providers/base.py`. Add tests with a mocked client.
+
+### Adding a tool
+
+Subclass `Tool` in `tools/`, give it a pydantic `args_schema`, register it in `build_tools` /
+`start_repl`, and describe what the user sees in `utils/tool_display.py`. If it changes files, make sure
+checkpoints can snapshot it (`core/checkpoints.py`). Tools that can do damage need permission handling in
+`config/permissions.py`.
+
+### Adding a slash command
+
+Add it to `SLASH_COMMANDS` in `cli/constants.py` (that feeds the dropdown and `/help`) and handle it in the
+REPL in `cli/main.py`; put non-trivial logic in `cli/repl_commands.py` so it can be tested. A test fails if a
+command appears in the dropdown without a handler.
+
+## Testing notes
+
+- Tests must not touch your real `~/.devorch`: monkeypatch `Path.home()` and the config paths (see
+  `tests/test_repl_commands.py` for a fixture).
+- Do not assert on `--help` text; it is colourised and wrapped differently per terminal. Inspect the
+  registered options instead.
+- Terminal UI behaviour (layout, colours, key bindings) is tested on a virtual terminal with
+  `tests/_screen.py` (uses `pyte`), so it can be verified without a real terminal.
+- Mock the model: provider tests use fake clients, never live APIs.
+
+## Releasing (maintainers)
+
+1. Bump the version in `pyproject.toml` **and** `cli/constants.py`, and add the `CHANGELOG.md` entry.
+2. Merge to `main`, then push a `vX.Y.Z` tag. The publish workflow builds, uploads to PyPI and creates the
+   GitHub release. Published versions cannot be reused, so double-check before tagging.

devorch-0.5.0/DEVORCH.md

@@ -0,0 +1,48 @@
+# DevOrch - AI Coding Assistant CLI
+
+## Overview
+DevOrch is an enterprise-ready, multi-provider AI coding assistant CLI with support for 13+ LLM providers, interactive REPL, persistent sessions, tool execution, MCP servers, and background terminal processes.
+
+## Tech Stack
+- **Language**: Python 3.10+ (tested on Python 3.10-3.13)
+- **CLI Framework**: Typer, Questionary, Prompt Toolkit, Rich
+- **AI / SDKs**: OpenAI, Anthropic, Google GenAI SDK, HTTPX
+- **Data Validation**: Pydantic v2
+- **Testing & Quality**: Pytest, Pytest-asyncio, Ruff, Mypy
+
+## Architecture & Project Structure
+- `cli/`: CLI entrypoints, Typer commands (`ask`, `edit`, `run`, `init`), slash command handlers, banners, and REPL.
+- `core/`: Agent orchestration engine:
+  - `agent.py`: Main agentic loop, tool calling, execution loop, plan mode approval.
+  - `context.py`: Token estimation, context compaction, tool output pruning, token usage tracking.
+  - `loop_detector.py`: Duplicate call detection, oscillation detection, error thrashing prevention, turn advisories.
+  - `project_context.py`: Auto-discovers and loads repository instructions (`DEVORCH.md`, `CLAUDE.md`, `AGENTS.md`).
+  - `executor.py`: Tool permission enforcement and invocation.
+  - `planner.py`: Message preparation and system prompt injection.
+  - `sessions.py`: Session persistence, continuation, and summarization.
+  - `modes.py`: Agent execution modes (`ASK`, `AUTO`, `PLAN`).
+  - `memory.py` & `skills.py`: Persistent memory and skill definitions.
+- `tools/`: Built-in tools:
+  - `filesystem.py`: File reading with pagination, writing, directory listing.
+  - `edit.py`: Surgical find/replace, line-based editing, diff generation.
+  - `grep.py`: Fast regex pattern search across text files.
+  - `search.py`: Glob-based file and directory search.
+  - `shell.py` & `terminal_session.py`: Shell execution and persistent terminal sessions.
+- `providers/`: Unified LLM provider adapters (`openai`, `anthropic`, `gemini`, `groq`, `deepseek`, etc.).
+- `schemas/`: Dataclasses for `Message`, `ToolCall`, `LLMResponse`, `TokenUsage`.
+
+## Common Commands
+- **Run Tests**: `pytest` or `python -m pytest`
+- **Run Single Test**: `pytest tests/test_context.py`
+- **Lint**: `ruff check .`
+- **Format**: `ruff format .`
+- **Type Check**: `mypy .`
+- **Run DevOrch Locally**: `devorch` or `python -m cli.main`
+
+## Coding Standards & Minimal Token Guidelines
+1. **Find Before Reading**: Always use `search` (to find file paths) or `grep` (to find symbols/definitions) before reading file contents.
+2. **Inspect Surgically**: Use `filesystem` with `action="read_lines"` or specific line ranges rather than dumping huge files.
+3. **Edit Surgically**: Use `edit` with `action="replace"` or `action="replace_lines"` to generate clean unified diffs. Avoid full file rewrites whenever possible.
+4. **Prevent Loops**: Never repeat identical tool calls with the same arguments. If a tool fails or finds nothing, alter the query or check file paths.
+5. **Verify Changes**: After modifying code, always run the relevant pytest test suite to verify correctness before reporting completion.
+6. **Preserve Compatibility**: Keep type hints compatible with Python 3.10+ (use `|` for unions or `Optional`/`Union`).