mini-code-cli 0.1.1.2__tar.gz → 0.1.1.3__tar.gz

mini_code_cli-0.1.1.3/PKG-INFO

@@ -0,0 +1,390 @@
+Metadata-Version: 2.4
+Name: mini-code-cli
+Version: 0.1.1.3
+Summary: Mini Coding Agent. Allows you to easily experiment with a small coding agent.
+Author-email: Nikolai Rozanov <nikolai.rozanov@gmail.com>
+License-Expression: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/ai-nikolai/mini-code-cli
+Classifier: Programming Language :: Python :: 3
+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: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+Dynamic: license-file
+
+# mini-code-cli
+
+### A minimal coding agent CLI
+
+> No bloat, no dependencies, no tracking, no telemetry...
+
+[![CI](https://img.shields.io/github/actions/workflow/status/ai-nikolai/mini-code-cli/ci.yml?branch=main&label=CI&logo=github&style=flat-square)](https://github.com/ai-nikolai/mini-code-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mini-code-cli?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/mini-code-cli/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/mini-code-cli/)
+[![Stars](https://img.shields.io/github/stars/ai-nikolai/mini-code-cli?style=flat-square&logo=github)](https://github.com/ai-nikolai/mini-code-cli/stargazers)
+[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square)](LICENSE)
+[![Cite](https://img.shields.io/badge/cite-BibTeX-blueviolet?style=flat-square&logo=latex&logoColor=white)](#citation)
+
+**Purpose:** a no-bloat, minimal coding CLI to enjoy experimenting and researching!
+
+**Install** · [Quick start](#quick-start) · [Modes &amp; safety](#modes--safety) · [Options](#command-line-options) · [Tools](#available-tools) · [Sub-agents](#sub-agents) · [In-session commands](#in-session-commands) · [Development](#development) · [Docs](#documentation) · [Citation](#citation)
+
+> [!TIP]
+> **New here?** `pip install mini-code-cli`, point it at a model (a local server on
+> `localhost:30000`, or `MINI_CODE_API_KEY` + `--url`), and run `mini-code`. Everything else
+> is optional.
+
+## Install
+
+```bash
+pip3 install mini-code-cli
+```
+
+- **PyPI:** <https://pypi.org/project/mini-code-cli/>
+- **Python:** `>= 3.10` &nbsp;·&nbsp; **runtime dependency:** `requests` only
+- **From source / contributing:** see [docs/README_DEV.md](docs/README_DEV.md)
+
+## Quick start
+
+**1 — Local model** (e.g. vLLM or SGLang on port 30000; see [serving a model locally](#serving-a-model-locally)):
+
+```bash
+mini-code                          # talks to http://0.0.0.0:30000/v1
+```
+
+**2 — Hosted / custom API:**
+
+```bash
+export MINI_CODE_API_KEY="sk-YOUR_API_KEY"
+mini-code --url "https://api.deepseek.com" --model "deepseek-v4-flash"
+```
+
+**3 — The shortcuts** (plan mode, sub-agents, shell, auto-mode, no permission prompts):
+
+```bash
+mini-code --all                    # = --plan --enable-subagents --enable-shell --auto-mode --sudo
+mini-code --all-last               # ...and continue your last session
+```
+
+**4 — A first prompt:**
+
+```txt
+Write an agent.md file for me that helps an LLM write efficient triton kernels,
+given a reference implementation.
+```
+
+> [!NOTE]
+> **Every flag** is listed once, in [Command-line options](#command-line-options) — or run
+> `mini-code --help`. Modes and their caveats are described in [Modes & safety](#modes--safety).
+
+## Command-line options
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `--url URL` | `http://0.0.0.0:30000` | API host |
+| `--model MODEL` | — | model name |
+| `--api-key KEY` | `$MINI_CODE_API_KEY` | API key for authentication |
+| `--max-tokens N` | — | reply budget; also the output headroom used when deriving the compaction limit |
+| `--temperature T` | `1.0` | sampling temperature |
+| `--system-prompt TEXT` | built-in | replace the system prompt (an `--agent-md` file is appended *after* it) |
+| `--prompt TEXT` | — | initial user prompt |
+| `-a`, `--auto-mode` | off | keep querying the model and running tools until no tool calls remain |
+| `--agent-md FILE` | — | append an `agent.md` file after the system prompt (e.g. `./skill.md`) |
+| `--ask-permission` | off | ask before every tool call (ALLOW-tier shell commands still skip the prompt) |
+| `--sudo` | off | **dangerous:** never ask. DENY-tier commands are still refused |
+| `--allowed-dir DIR` | `./` | sandbox for **file** tools (does not restrict the shell) |
+| `-s`, `--enable-shell` | off | allow shell execution (classifier always applies) |
+| `-g`, `--enable-subagents` | off | expose sub-agents as tools |
+| `--skills` | off | enable the `.mini` skills directory (`skill.md`s, `SKILLS.md`, runnable scripts) |
+| `-p`, `--plan` | off | plan mode (`CURRENT_GOAL.md` / `CURRENT_PLAN.md`, `/plan`) |
+| `--llm-timeout S` | `500` | HTTP timeout for LLM requests |
+| `--tool-timeout S` | `120` | timeout for a single tool call |
+| `--max-context-tokens N` | derived | input-token budget before the history is compacted |
+| `--cache-dir DIR` | `~/.cache/mini/sessions/` | where session histories are stored |
+| `--restore-session PATH` | — | continue a specific previous session |
+| `-l`, `--load-last-session` | off | continue the session recorded in the `.mini` pointer |
+| `--all` | off | `--plan --enable-subagents --enable-shell --auto-mode --sudo` |
+| `--all-last` | off | `--all` + `--load-last-session` |
+| `--verbose` | off | print full detail (default: user/assistant turns, token usage, tool calls only) |
+| `-h`, `--help` | — | show the built-in help |
+
+## Available tools
+
+The agent can call a small set of tools, all defined in `mini_code_cli/tools.py`. Every
+parameter a model does not need is defaulted, so omitting it keeps the previous behaviour.
+
+| Tool | What it does |
+| --- | --- |
+| `read_file` | read a file; `offset` (1-based line) and `limit` page through large files |
+| `write_file` | write/overwrite; `append` adds to the end, `create_dirs` creates parents |
+| `edit` | replace an **exact** string (`old_string` → `new_string`); refuses a missing or ambiguous match unless `replace_all` |
+| `grep` | regex search a file or directory; `recursive`, `include`, `ignore_case`, `line_numbers`, `max_results` (noise dirs skipped) |
+| `glob` | list files matching a glob (one per line, `**` supported), optionally against a `root` |
+| `web_search` | best-effort lookup: related queries + a short Wikipedia extract. Never raises |
+| `read_website` | fetch raw text/HTML of a URL (bounded by `--tool-timeout`), `max_chars` caps size |
+| `run_shell_command` | run a shell command (needs `--enable-shell`); `cwd`, `timeout`, and stdout/stderr/exit code are all reported |
+
+## Sub-agents
+
+`--enable-subagents` lets the main agent **delegate a focused task** to a sub-agent, exposed to
+the model as an extra tool. A sub-agent is a self-contained, narrowed agent: it runs unattended
+in auto-mode, in its own isolated session folder, and hands back a short text result (plus an
+optional `report.md`). It reuses all the existing machinery — tools, the shell-safety
+classifier, the `--allowed-dir` sandbox, compaction and `--plan` — and cannot spawn further
+sub-agents.
+
+```bash
+mini-code --enable-subagents       # the available sub-agents then show up in /help
+```
+
+| Sub-agent | What it is for |
+| --- | --- |
+| `research` | read-only web research: searches, reads a few sources, returns a sourced summary. Can only use `web_search` / `read_website` — never the filesystem or shell. Optional `sources` hint (e.g. `"wikipedia.org only"`) |
+| `planner` | drafts or refines a step-by-step plan for a goal; always runs in plan mode |
+| `software_engineer` | writes, edits, refactors, fixes and tests code; can run shell commands (tests, builds) to verify |
+| `generic` | general-purpose helper for anything that fits no narrower agent |
+
+> [!NOTE]
+> A sub-agent's `tools`, `enable_shell` and `max_steps` are always **intersected with the
+> parent's** permissions, so it can never do anything the main agent could not. Sub-agents
+> compose with `--plan`: each keeps its own `CURRENT_PLAN.md` / `CURRENT_GOAL.md`.
+
+<details>
+<summary><b>Adding your own sub-agent</b></summary>
+
+A sub-agent is just a small class — subclass `SubAgent` and register it:
+
+```python
+# my_subagents.py
+from mini_code_cli.subagents import SubAgent, register
+
+class SummarizeSubAgent(SubAgent):
+    name = "summarize"
+    description = "Summarize a piece of text the main agent provides."
+    tools = ["read_file", "write_file"]   # restrict the nested agent's tools
+    enable_shell = False
+    max_steps = 5
+
+register(SummarizeSubAgent())
+```
+
+Make sure the module is imported (e.g. `import my_subagents`) and it is discovered and exposed
+to the model automatically when `--enable-subagents` is set. See
+`mini_code_cli/subagents/builtin.py` for every knob and
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) (sections 2–3) for the design.
+
+</details>
+
+## In-session commands
+
+| Command | What it does |
+| --- | --- |
+| `/history` | list the conversation (turn number, what happened, where) |
+| `/history <n>` | show the full messages recorded for turn `n` |
+| `/history last` | ...for the most recent turn |
+| `/reset [<n>]` | rewind to the end of turn `n` (`last` works too); drops everything after it |
+| `/clear` | clear the screen (keeps the conversation history) |
+| `/plan` | show the current goal + plan (plan mode only) |
+| `/help` | show this help |
+| `/quit`, `/exit` | save the session and exit |
+
+> [!NOTE]
+> `/history` and `/reset` are driven by `summary_history.json`, a flat recorder that maps every
+> turn to the `history_{n}.json` segment and message index it lives in — so no full history is
+> read just to list the conversation.
+>
+> * **`<n>` is validated**: `last`, or a positive 1-based turn number. `0`, negatives and
+>   non-numbers are rejected with `No such turn` instead of silently showing a different turn.
+> * **A bare `/reset` never destroys anything**: it reports `Already at turn N` when the
+>   transcript already ends at the last recorded turn, and *warns instead of truncating* if
+>   there are messages that were never recorded. Only `/reset <n>` / `/reset last` rewind.
+> * **A rewind really sticks**: the target `history_{n}.json` is truncated in place (no backup)
+>   and every higher `history_{m}.json` / `usage_{m}.json` segment is deleted, so a restart
+>   cannot resurrect the dropped turns. All history files are written atomically.
+> * **Token usage is never rolled back**: a rewind does not un-spend tokens, and the session
+>   total is preserved. See
+>   [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#rewinding-reset-and-what-it-does-to-the-files)
+>   for the files involved.
+
+## Development
+
+Linting, the test suite, CI and the release process are documented in
+[**docs/README_DEV.md**](docs/README_DEV.md).
+
+```bash
+python3 scripts/lint.py                                # lint (standard library only)
+python3 -m unittest discover -s tests -p "test_*.py"    # run the test suite
+```
+
+Releases are cut by tagging `main`: pushing a `v*` tag triggers
+[`.github/workflows/release.yml`](.github/workflows/release.yml), which builds the sdist + wheel,
+verifies them with `twine check`, and attaches them to a new GitHub release.
+
+## Documentation
+
+Everything beyond this README lives in [`docs/`](docs/):
+
+| Document | What it covers |
+| --- | --- |
+| [**docs/README_DEV.md**](docs/README_DEV.md) | developer guide — local setup, repository layout, linting, the test suite, CI and the release / PyPI upload process |
+| [**docs/ARCHITECTURE.md**](docs/ARCHITECTURE.md) | design — module layout, on-disk conversation state (`history_{n}.json`, `summary_history.json`, usage files), the sub-agent framework and how to extend it |
+
+This README stays the user-facing entry point (install, CLI flags, tools, sub-agents,
+in-session commands, modes &amp; safety); the two documents above go deeper on the developer
+and design side.
+
+## Modes & safety
+
+### Shell execution — `-s` / `--enable-shell`
+
+Everything the agent runs from the shell first passes a **safety classifier** that sorts the
+command into one of three tiers:
+
+| Tier | Examples | What happens |
+| --- | --- | --- |
+| **DENY** | `rm -rf /`, `dd of=/dev/...`, `mkfs.*`, fork bombs | refused outright, never run |
+| **ASK** | `rm file`, `sudo ...`, `chmod`, `curl ... \| sh` | requires your confirmation |
+| **ALLOW** | `ls`, `cat`, `git status` | runs without prompting |
+
+> [!WARNING]
+> The classifier is **always enforced** — even in auto-mode and with `--sudo` — so the agent
+> cannot run destructive commands unattended. It is a heuristic, not a sandbox: use it with care.
+> `--allowed-dir` sandboxes **file tools**, not the shell.
+
+### Plan mode — `-p` / `--plan`
+
+The loop keeps two human-readable tracking files in the session directory: `CURRENT_GOAL.md`
+(your latest instruction) and `CURRENT_PLAN.md` (a step-by-step plan for that goal, marked
+finished when it is done). They are authored by the *loop*, not the agent, live outside
+`--allowed-dir`, and can be inspected any time with `/plan`.
+
+> [!NOTE]
+> Plan mode also changes **history compaction**: after the transcript is compacted to a summary,
+> `CURRENT_PLAN.md` and `CURRENT_GOAL.md` are re-injected, so the agent keeps working against the
+> same goal. When the work looks done the plan is reviewed and any outstanding task is re-queued
+> before the agent returns to you.
+
+### Sessions — resume, or start fresh
+
+Every session is saved under `--cache-dir` (default `~/.cache/mini/sessions/`).
+
+> [!TIP]
+> If a previous session exists but you did **not** ask to resume one (neither
+> `--load-last-session` nor `--restore-session`), the prompt offers **Resume / Start new / Exit**
+> before the conversation begins. Ctrl-C or EOF there is a graceful exit. This is the *asking*
+> variant; `--load-last-session` is the *silent* one.
+
+
+| Flag | Behaviour |
+| --- | --- |
+| `--restore-session PATH` | continue that exact session (a session directory or a bare session id under `--cache-dir`) |
+| `-l`, `--load-last-session` | continue the session recorded in the `.mini/last_session.json` pointer, without asking |
+
+`--load-last-session` continues that session **in place** (same id, same folder, same
+messages), so the conversation you were in is the one you get back; an explicit
+`--restore-session` wins if both are given. The "most recent" session comes from a single
+source — the tiny `.mini/last_session.json` pointer written when a session starts or is
+restored inside `--allowed-dir` (deliberately no timestamp fallback: with no pointer, a fresh
+session starts). That pointer lives in the same `.mini` directory as `--skills`, but as its
+own dedicated file, so the two never clash.
+
+A session folder is restorable only if it has what this version writes: a valid
+`summary_history.json` recorder, plus the `history_{n}.json` segment its last record names
+(usage files are optional). Anything else — a folder from an older release, a hand-assembled
+transcript, a recorder that does not validate, a missing segment — is **refused with a note
+saying why**, and a fresh session is started instead. Nothing is repaired, guessed at, or
+written into the refused folder.
+
+### Context compaction — `--max-context-tokens`
+
+Compaction is decided by **tokens only**, never by message count: a few large tool outputs can
+fill a window that hundreds of short turns would not. The next request is projected from the
+server-reported `prompt_tokens`, plus an estimate of what was appended since, plus the output
+reserve (`--max-tokens`). Unset (default) it is derived from the model's context window minus the
+output reserve and a safety margin. Lower it to compact sooner, raise it to compact later — there
+is no message-count cap to configure.
+
+Compaction replaces the older turns with a summary, but it always carries the **turn in flight**
+across the rollover: the message you just typed (or, mid-turn, the tool call the model is
+waiting on) is kept verbatim after the summary. So a compaction that fires just as you send an
+instruction cannot swallow it — the model still answers what you asked, and the turn stays in
+the session file, in `/history` and in a later restore.
+
+Because a rollover leaves no trace in the transcript (the old turns really are gone), the
+console says in plain terms what happened — all of it without `--verbose`:
+
+```
+[!] Compacting the conversation: 42 messages -> a summary (51000 tokens in, 8192 reserved for the reply > 52000 budget). The current turn (1 message) is kept verbatim.
+[!] Summary preview: The user asked for a token-based compaction trigger, then fixed ...
+[!] Compacted history_0.json (42 messages) into a summary; history_1.json now starts with 3 messages (summary + 1 kept message).
+```
+
+So you can see *what* was folded away (a preview of the summary itself), *how much* (the
+message count of the segment that was closed), *where it went* (`history_0.json` closed,
+`history_1.json` started) and that nothing you just typed was lost. If the summariser answers
+with an empty summary twice, or the call fails, compaction is abandoned and the note says so
+explicitly — "nothing was lost, but the next request may still be too large" — with the
+transcript and the segment left untouched.
+
+### Exiting — the good-bye box
+
+Quitting (`/quit`, `exit`, or EOF on stdin) saves the session and then prints a short yellow
+box: the version, a sign-off, and what the session left behind — session id, folder, the
+history segments on disk, how many turns were recorded, and the token / call totals.
+
+```
+╔══════════ MiniCodeCLI v0.1.1.2 - goodbye ═════════════════════╗
+║ Goodbye, and thanks for using MiniCodeCLI!                    ║
+║                                                               ║
+║ session id   : 1792666273983619-36ca3c2e                      ║
+║ saved under  : ~/.cache/mini/sessions/1792…-36ca3c2e/         ║
+║ history      : history_0.json (segment 0), 5 messages         ║
+║ conversation : 2 recorded turns                               ║
+║ tokens       : 20 in / 10 out (30 total)                      ║
+║ calls        : 2 LLM, 0 tool                                  ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+It is printed exactly once, and only on a normal exit: a Ctrl-C or an internal error already
+says what went wrong in red, so it does not get a cheerful summary box on top. With `--verbose`
+the old per-field `Token usage (this session)` block is printed above it as well.
+
+
+## Serving a model locally
+
+Tested with vLLM v0.30 (tool calling enabled):
+
+```bash
+vllm serve ornith-ai/Ornith-1.5-397B-FP8 \
+    --tensor-parallel-size 4 \
+    --host 0.0.0.0 \
+    --port 30000 \
+    --enable-auto-tool-choice \
+    --tool-call-parser qwen3_xml \
+    --reasoning-parser qwen3 \
+    --trust-remote-code
+```
+
+## Citation
+
+If you use `mini-code-cli` in your research or writing, please cite it:
+
+```bibtex
+@misc{mini-code-cli,
+  author       = {Rozanov, Nikolai},
+  title        = {mini-code-cli: A minimal, dependency-light coding agent},
+  year         = {2026},
+  version      = {0.1.1.2},
+  howpublished = {\url{https://github.com/ai-nikolai/mini-code-cli}},
+  note         = {A no-bloat, dependency-light agent CLI for experimenting.}
+}
+```
+
+## License
+
+[AGPL-3.0](LICENSE) — (C) Nikolai Rozanov, 2026 – present.

{mini_code_cli-0.1.1.2 → mini_code_cli-0.1.1.3}/README.md

@@ -11,7 +11,7 @@
 [![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square)](LICENSE)
 [![Cite](https://img.shields.io/badge/cite-BibTeX-blueviolet?style=flat-square&logo=latex&logoColor=white)](#citation)
 
-**Purpose:** a no-bloat, minimal coding CLI to enjoy experimenting and researching.
+**Purpose:** a no-bloat, minimal coding CLI to enjoy experimenting and researching!
 
 **Install** · [Quick start](#quick-start) · [Modes & safety](#modes--safety) · [Options](#command-line-options) · [Tools](#available-tools) · [Sub-agents](#sub-agents) · [In-session commands](#in-session-commands) · [Development](#development) · [Docs](#documentation) · [Citation](#citation)
 
@@ -312,6 +312,29 @@ with an empty summary twice, or the call fails, compaction is abandoned and the
 explicitly — "nothing was lost, but the next request may still be too large" — with the
 transcript and the segment left untouched.
 
+### Exiting — the good-bye box
+
+Quitting (`/quit`, `exit`, or EOF on stdin) saves the session and then prints a short yellow
+box: the version, a sign-off, and what the session left behind — session id, folder, the
+history segments on disk, how many turns were recorded, and the token / call totals.
+
+```
+╔══════════ MiniCodeCLI v0.1.1.2 - goodbye ═════════════════════╗
+║ Goodbye, and thanks for using MiniCodeCLI!                    ║
+║                                                               ║
+║ session id   : 1792666273983619-36ca3c2e                      ║
+║ saved under  : ~/.cache/mini/sessions/1792…-36ca3c2e/         ║
+║ history      : history_0.json (segment 0), 5 messages         ║
+║ conversation : 2 recorded turns                               ║
+║ tokens       : 20 in / 10 out (30 total)                      ║
+║ calls        : 2 LLM, 0 tool                                  ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+It is printed exactly once, and only on a normal exit: a Ctrl-C or an internal error already
+says what went wrong in red, so it does not get a cheerful summary box on top. With `--verbose`
+the old per-field `Token usage (this session)` block is printed above it as well.
+
 
 ## Serving a model locally
 
@@ -337,9 +360,9 @@ If you use `mini-code-cli` in your research or writing, please cite it:
   author       = {Rozanov, Nikolai},
   title        = {mini-code-cli: A minimal, dependency-light coding agent},
   year         = {2026},
-  version      = {0.1.1.0},
+  version      = {0.1.1.2},
   howpublished = {\url{https://github.com/ai-nikolai/mini-code-cli}},
-  note         = {A no-bloat, dependency-free agent CLI for experimenting.}
+  note         = {A no-bloat, dependency-light agent CLI for experimenting.}
 }
 ```
 

mini_code_cli-0.1.1.3/mini_code_cli/__init__.py

@@ -0,0 +1,59 @@
+"""mini_code_cli -- package metadata (the version shown in the welcome banner).
+
+The version is read from ``pyproject.toml`` first: that file is the source of
+truth when running from a checkout, and the *installed* metadata is often stale
+(a plain ``pip install -e .`` keeps the version it was installed at, so bumping
+``pyproject.toml`` would leave the banner reporting an old number). If the file
+cannot be read, fall back to the installed distribution's metadata and finally
+to ``"unknown"`` so importing the package can never fail over a version lookup.
+"""
+
+__all__ = ["__version__"]
+
+
+def _version_from_file(path):
+    """Return the ``[project] version`` in ``path``.
+
+    ``tomllib`` only exists from Python 3.11, and the scan below is not a
+    nicety for 3.10: without it this function used to skip the file entirely on
+    that interpreter and report the *installed* metadata instead, so a checkout
+    with a stale editable install showed the wrong version in the banner (found
+    on the 3.10 CI leg). Both paths read the same key, and the section tracking
+    matters: a ``version`` key in some other table must not win.
+    """
+    try:
+        import tomllib  # Python >= 3.11
+    except ImportError:  # pragma: no cover - exercised on the 3.10 CI leg
+        tomllib = None
+    if tomllib is not None:
+        with open(path, "rb") as f:
+            return str(tomllib.load(f)["project"]["version"])
+    section = None
+    with open(path, encoding="utf-8") as f:
+        for line in f:
+            stripped = line.strip()
+            if stripped.startswith("["):
+                section = stripped
+            elif section == "[project]" and stripped.startswith("version"):
+                return stripped.split("=", 1)[1].strip().strip('"')
+    raise KeyError(f"no version in the [project] table of {path}")
+
+
+def _read_version():
+    """Best-effort package version: pyproject.toml, then installed metadata."""
+    try:
+        from pathlib import Path
+
+        pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+        return _version_from_file(pyproject)
+    except Exception:
+        pass
+    try:
+        from importlib.metadata import version as _dist_version
+
+        return _dist_version("mini-code-cli")
+    except Exception:
+        return "unknown"
+
+
+__version__ = _read_version()

mini_code_cli-0.1.1.3/mini_code_cli/__main__.py

@@ -0,0 +1,12 @@
+"""Allow ``python -m mini_code_cli`` to start the agent.
+
+The console script ``mini-code`` (see ``[project.scripts]``) is the normal entry
+point; this module exists so the package also runs straight from a checkout or
+an installed wheel without the script on ``PATH`` -- which is what a reader
+tries first after ``pip install -e .``.
+"""
+
+from .agent_loop import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{mini_code_cli-0.1.1.2 → mini_code_cli-0.1.1.3}/mini_code_cli/agent_loop.py

@@ -31,7 +31,7 @@ from . import prompts
 from . import shell_safety_utils
 from . import tools
 from . import utils
-from .utils import oneline
+from .utils import oneline, plural
 from . import ui
 from . import subagents
 from . import skills
@@ -118,7 +118,12 @@ def _safe_int(value, default=0):
 # ---------------------------------------------------------------------------
 
 def parse_args():
-    parser = argparse.ArgumentParser(description="Agent loop for interacting with a language model")
+    # ``prog`` is pinned so ``--help`` reads the same whether the agent was
+    # started through the ``mini-code`` script, ``python -m mini_code_cli`` or
+    # a test harness (without it, the usage line said ``__main__.py``).
+    parser = argparse.ArgumentParser(
+        prog="mini-code",
+        description="Agent loop for interacting with a language model")
     # MODEL / LLM related
     parser.add_argument("--url", type=str, default=f"{DEFAULT_MODEL_URL}", help=f"API host, default={DEFAULT_MODEL_URL}")
     parser.add_argument("--max-tokens", type=int, help="Maximum tokens for a single LLM response (the reply budget), default=None. Also used as the output headroom reserved when deriving the compaction limit from the model's context window.")
@@ -298,11 +303,6 @@ def _in_flight_tail(messages):
     return []
 
 
-def _plural(count, noun, suffix="s"):
-    """``"1 message"`` / ``"4 messages"`` -- for messages the user reads."""
-    return f"{count} {noun}" + ("" if count == 1 else suffix)
-
-
 def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats,
                   history_index=0, token_limit=None, reserved_output_tokens=0,
                   current_tokens=None, plan_hook=None, console=None):
@@ -358,12 +358,12 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
     # stake; a compaction note that stays silent about that is exactly what makes
     # the rollover look like it might have eaten the message.
     tail = _in_flight_tail(messages)
-    kept_note = (f" The current turn ({_plural(len(tail), 'message')}) is kept "
+    kept_note = (f" The current turn ({plural(len(tail), 'message')}) is kept "
                  f"verbatim." if tail else "")
 
     try:
         console.note(
-            f"Compacting the conversation: {_plural(len(messages), 'message')} "
+            f"Compacting the conversation: {plural(len(messages), 'message')} "
             f"-> a summary ({reason}).{kept_note}", "warn")
         summary_prompt = prompts.compaction_prompt(messages)
 
@@ -404,7 +404,7 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
             # may still be too large.
             console.note(
                 f"Could not compact history: the summariser returned an empty "
-                f"summary twice. Keeping all {_plural(len(messages), 'message')} "
+                f"summary twice. Keeping all {plural(len(messages), 'message')} "
                 f"and history_{history_index}.json as they are -- nothing was "
                 f"lost, but the next request may still be too large "
                 f"({reason}).", "warn")
@@ -449,7 +449,7 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
         # and *where it went* (which segment file was closed and which was
         # started).
         console.note(f"Summary preview: {utils.oneline(summary, 120)}", "warn")
-        kept = (f"summary + {_plural(len(tail), 'kept message')}" if tail
+        kept = (f"summary + {plural(len(tail), 'kept message')}" if tail
                 else "summary only")
         # Phrased as "old segment -> new segment" rather than "N messages -> M
         # messages": the replacement can be *longer* than what it replaced (a
@@ -457,9 +457,9 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
         # counts that sometimes grows reads like a bug.
         console.note(
             f"Compacted history_{history_index}.json "
-            f"({_plural(len(messages), 'message')}) into a summary; "
+            f"({plural(len(messages), 'message')}) into a summary; "
             f"history_{history_index + 1}.json now starts with "
-            f"{_plural(len(compacted), 'message')} ({kept}).", "warn")
+            f"{plural(len(compacted), 'message')} ({kept}).", "warn")
         # A new segment (history_index + 1) is started on compaction: the
         # compacted messages are its snapshot, and every later turn appends
         # to it. The caller records a single high-level 'summary' turn for
@@ -468,7 +468,7 @@ def maybe_compact(messages, server_url, model, api_key, llm_timeout, token_stats
     except Exception as e:
         console.note(
             f"Failed to compact history: {e}. Keeping all "
-            f"{_plural(len(messages), 'message')} unchanged.", "error")
+            f"{plural(len(messages), 'message')} unchanged.", "error")
 
     return messages, False, history_index
 
@@ -1960,7 +1960,9 @@ class AgentSession:
         #    just the turns. In verbose mode everything is printed permanently.
         transient = not self.console.verbose
         func = self.tools_dict[name]["function"]
-        result = call_function_with_timeout(func, tool_params, name, timeout_seconds=self.args.tool_timeout)
+        result = call_function_with_timeout(func, tool_params, name,
+                                            timeout_seconds=self.args.tool_timeout,
+                                            console=self.console)
 
         self.console.tool_call_display(name, tool_params, result, transient=transient)
         self._append_tool_result(call_id, str(result))
@@ -2105,8 +2107,8 @@ class AgentSession:
             ("session id", self.unique_id),
             ("saved under", f"{self.cache_dir}/{self.unique_id}/"),
             ("history", f"{where} (segment {self.history_index}), "
-                        f"{_plural(len(self.messages), 'message')}"),
-            ("conversation", _plural(turns, "recorded turn")),
+                        f"{plural(len(self.messages), 'message')}"),
+            ("conversation", plural(turns, "recorded turn")),
             ("tokens", f"{count('prompt_tokens'):,} in / "
                        f"{count('completion_tokens'):,} out "
                        f"({count('total_tokens'):,} total)"),
@@ -2176,7 +2178,7 @@ class AgentSession:
             save_history(self.messages, self.cache_dir, self.unique_id, self.history_index)
             self._record_turn(
                 f"summary: history_{new_index - 1}.json "
-                f"({_plural(len(closing_messages), 'message')}) compacted into a "
+                f"({plural(len(closing_messages), 'message')}) compacted into a "
                 f"summary; history_{self.history_index}.json started",
                 self.messages)