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

{mini_code_cli-0.1.1.3 → mini_code_cli-0.1.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mini-code-cli
-Version: 0.1.1.3
+Version: 0.1.1.4
 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
@@ -67,7 +67,7 @@ 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                    # = --plan --enable-subagents --enable-shell --skills --auto-mode --sudo
 mini-code --all-last               # ...and continue your last session
 ```
 
@@ -95,20 +95,23 @@ given a reference implementation.
 | `--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) |
+| `--ask-permission` | off | ask before **every** tool call, including an ALLOW-tier shell command (`--sudo` disables all prompts) |
 | `--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`) |
+| `--skills` | off | enable the `.mini` skills directory (`skill.md`s, `SKILLS.md`, runnable scripts). **`run_skill` executes those Python scripts — arbitrary code execution, even without `--enable-shell`**; only enable it for a directory you trust |
+| `-p`, `--plan` | off | plan mode (`CURRENT_GOAL.md` / `CURRENT_PLAN.md`, printed plan, `/plan`, `/skip-plan`) |
+| `--plan-strategy NAME` | `plan-verify-step` | `plan-verify-step`, `plan-verify` or `open-plan` (implies `--plan`) |
+| `--scratchpad` | off | give the agent a free-form `.mini/SCRATCHPAD.md` (plus further scratch files) for thoughts, plans and learnings |
+| `--compaction-strategy NAME` | `summarise` | `summarise`, `predict-files` or `predict-messages` |
 | `--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` | off | `--plan --enable-subagents --enable-shell --skills --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 |
@@ -151,8 +154,10 @@ mini-code --enable-subagents       # the available sub-agents then show up in /h
 
 > [!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`.
+> parent's** permissions, so it can never do anything the main agent could not. The `tools`
+> allowlist is enforced on the nested session itself (both the schemas offered to the model and
+> the dispatch table), not merely described in its prompt. 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>
@@ -190,9 +195,16 @@ to the model automatically when `--enable-subagents` is set. See
 | `/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) |
+| `/context` | show how the context window is used: tokens and percentages by category (system prompt, user/assistant messages, tool calls/outputs, reasoning, overhead) |
+| `/skip-plan <prompt>` | send `<prompt>` once without generating or reviewing a plan |
 | `/help` | show this help |
 | `/quit`, `/exit` | save the session and exit |
 
+**Multi-line input:** press `Shift+Enter` (or `Ctrl-J`) to insert a newline; plain
+`Enter` sends the turn. This works in the session prompt and the startup tip
+reminds you. Terminals that report `Shift+Enter` as a CSI-u/modifyOtherKeys
+sequence are recognised; elsewhere `Ctrl-J` inserts the newline.
+
 > [!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
@@ -251,6 +263,9 @@ command into one of three tiers:
 | **ASK** | `rm file`, `sudo ...`, `chmod`, `curl ... \| sh` | requires your confirmation |
 | **ALLOW** | `ls`, `cat`, `git status` | runs without prompting |
 
+`--sudo` removes the confirmation prompts (ASK tier and `--ask-permission`); DENY commands are
+still refused. With no flags, an ASK-tier command prompts and an ALLOW-tier one runs unaided.
+
 > [!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.
@@ -261,13 +276,34 @@ command into one of three tiers:
 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`.
+`--allowed-dir`, and can be inspected any time with `/plan`. The generated plan is
+also printed as a box right after planning, so you can see it without asking.
+Use `/skip-plan <prompt>` to send one prompt without planning it (plan mode stays
+on for later turns).
+
+`--plan-strategy` selects how planning is wired:
+
+| Strategy | What happens |
+| --- | --- |
+| `plan-verify-step` (default) | Current behaviour: author a plan, review it once the work settles, then run one extra step and keep whatever that step says. |
+| `plan-verify` | Same plan + review, but the post-review step is kept only when it calls a tool. A no-tool answer is shown to you and ends the turn without being appended to the transcript. |
+| `open-plan` | The agent owns a plan document at `.mini/PLAN.md` inside `--allowed-dir`, reads and updates it with the normal file tools, and the loop neither authors nor reviews a 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.
+> same goal. With `open-plan`, the agent's `.mini/PLAN.md` is re-injected instead. When the work
+> looks done the plan is reviewed and any outstanding task is re-queued before the agent returns
+> to you (except with `open-plan`).
+
+### Scratchpad — `--scratchpad`
+
+With `--scratchpad`, the loop creates `.mini/SCRATCHPAD.md` inside `--allowed-dir` and tells the
+agent that it may read and write that file freely, and may create additional scratch files in the
+same directory (for example `SCRATCH-NOTES.md`, `SCRATCH-IDEAS.md`). The scratchpad is ordinary
+state inside the sandbox, so the normal `read_file` / `write_file` / `edit` tools work; no special
+tool is registered. It is meant for the agent's own thoughts, plans, learnings and open questions,
+and survives a history compaction because it lives on disk.
 
 ### Sessions — resume, or start fresh
 
@@ -315,6 +351,20 @@ waiting on) is kept verbatim after the summary. So a compaction that fires just
 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.
 
+`--compaction-strategy` chooses what else survives besides the summary:
+
+| Strategy | Messages after compaction |
+| --- | --- |
+| `summarise` (default) | `system`, `summary`, `plan`, `current turn` |
+| `predict-files` | `system`, `summary`, predicted read-only tool calls + results, `plan`, `current turn` |
+| `predict-messages` | `system`, `summary`, original messages the model names by index, `plan`, `current turn` |
+
+`predict-files` asks the model which files it needs to re-read and executes only the read-only
+tools (`read_file`, `grep`, `glob`) it predicts; `predict-messages` asks for a JSON array of
+0-based message indexes to keep verbatim. Both predictions are one extra tool-free (or
+read-only-tool) LLM call, are billed normally, and are capped so they cannot refill the context
+they just freed. A failed prediction degrades to the plain summary.
+
 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`:
 
@@ -379,7 +429,7 @@ 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.2},
+  version      = {0.1.1.4},
   howpublished = {\url{https://github.com/ai-nikolai/mini-code-cli}},
   note         = {A no-bloat, dependency-light agent CLI for experimenting.}
 }

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

@@ -48,7 +48,7 @@ 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                    # = --plan --enable-subagents --enable-shell --skills --auto-mode --sudo
 mini-code --all-last               # ...and continue your last session
 ```
 
@@ -76,20 +76,23 @@ given a reference implementation.
 | `--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) |
+| `--ask-permission` | off | ask before **every** tool call, including an ALLOW-tier shell command (`--sudo` disables all prompts) |
 | `--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`) |
+| `--skills` | off | enable the `.mini` skills directory (`skill.md`s, `SKILLS.md`, runnable scripts). **`run_skill` executes those Python scripts — arbitrary code execution, even without `--enable-shell`**; only enable it for a directory you trust |
+| `-p`, `--plan` | off | plan mode (`CURRENT_GOAL.md` / `CURRENT_PLAN.md`, printed plan, `/plan`, `/skip-plan`) |
+| `--plan-strategy NAME` | `plan-verify-step` | `plan-verify-step`, `plan-verify` or `open-plan` (implies `--plan`) |
+| `--scratchpad` | off | give the agent a free-form `.mini/SCRATCHPAD.md` (plus further scratch files) for thoughts, plans and learnings |
+| `--compaction-strategy NAME` | `summarise` | `summarise`, `predict-files` or `predict-messages` |
 | `--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` | off | `--plan --enable-subagents --enable-shell --skills --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 |
@@ -132,8 +135,10 @@ mini-code --enable-subagents       # the available sub-agents then show up in /h
 
 > [!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`.
+> parent's** permissions, so it can never do anything the main agent could not. The `tools`
+> allowlist is enforced on the nested session itself (both the schemas offered to the model and
+> the dispatch table), not merely described in its prompt. 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>
@@ -171,9 +176,16 @@ to the model automatically when `--enable-subagents` is set. See
 | `/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) |
+| `/context` | show how the context window is used: tokens and percentages by category (system prompt, user/assistant messages, tool calls/outputs, reasoning, overhead) |
+| `/skip-plan <prompt>` | send `<prompt>` once without generating or reviewing a plan |
 | `/help` | show this help |
 | `/quit`, `/exit` | save the session and exit |
 
+**Multi-line input:** press `Shift+Enter` (or `Ctrl-J`) to insert a newline; plain
+`Enter` sends the turn. This works in the session prompt and the startup tip
+reminds you. Terminals that report `Shift+Enter` as a CSI-u/modifyOtherKeys
+sequence are recognised; elsewhere `Ctrl-J` inserts the newline.
+
 > [!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
@@ -232,6 +244,9 @@ command into one of three tiers:
 | **ASK** | `rm file`, `sudo ...`, `chmod`, `curl ... \| sh` | requires your confirmation |
 | **ALLOW** | `ls`, `cat`, `git status` | runs without prompting |
 
+`--sudo` removes the confirmation prompts (ASK tier and `--ask-permission`); DENY commands are
+still refused. With no flags, an ASK-tier command prompts and an ALLOW-tier one runs unaided.
+
 > [!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.
@@ -242,13 +257,34 @@ command into one of three tiers:
 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`.
+`--allowed-dir`, and can be inspected any time with `/plan`. The generated plan is
+also printed as a box right after planning, so you can see it without asking.
+Use `/skip-plan <prompt>` to send one prompt without planning it (plan mode stays
+on for later turns).
+
+`--plan-strategy` selects how planning is wired:
+
+| Strategy | What happens |
+| --- | --- |
+| `plan-verify-step` (default) | Current behaviour: author a plan, review it once the work settles, then run one extra step and keep whatever that step says. |
+| `plan-verify` | Same plan + review, but the post-review step is kept only when it calls a tool. A no-tool answer is shown to you and ends the turn without being appended to the transcript. |
+| `open-plan` | The agent owns a plan document at `.mini/PLAN.md` inside `--allowed-dir`, reads and updates it with the normal file tools, and the loop neither authors nor reviews a 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.
+> same goal. With `open-plan`, the agent's `.mini/PLAN.md` is re-injected instead. When the work
+> looks done the plan is reviewed and any outstanding task is re-queued before the agent returns
+> to you (except with `open-plan`).
+
+### Scratchpad — `--scratchpad`
+
+With `--scratchpad`, the loop creates `.mini/SCRATCHPAD.md` inside `--allowed-dir` and tells the
+agent that it may read and write that file freely, and may create additional scratch files in the
+same directory (for example `SCRATCH-NOTES.md`, `SCRATCH-IDEAS.md`). The scratchpad is ordinary
+state inside the sandbox, so the normal `read_file` / `write_file` / `edit` tools work; no special
+tool is registered. It is meant for the agent's own thoughts, plans, learnings and open questions,
+and survives a history compaction because it lives on disk.
 
 ### Sessions — resume, or start fresh
 
@@ -296,6 +332,20 @@ waiting on) is kept verbatim after the summary. So a compaction that fires just
 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.
 
+`--compaction-strategy` chooses what else survives besides the summary:
+
+| Strategy | Messages after compaction |
+| --- | --- |
+| `summarise` (default) | `system`, `summary`, `plan`, `current turn` |
+| `predict-files` | `system`, `summary`, predicted read-only tool calls + results, `plan`, `current turn` |
+| `predict-messages` | `system`, `summary`, original messages the model names by index, `plan`, `current turn` |
+
+`predict-files` asks the model which files it needs to re-read and executes only the read-only
+tools (`read_file`, `grep`, `glob`) it predicts; `predict-messages` asks for a JSON array of
+0-based message indexes to keep verbatim. Both predictions are one extra tool-free (or
+read-only-tool) LLM call, are billed normally, and are capped so they cannot refill the context
+they just freed. A failed prediction degrades to the plain summary.
+
 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`:
 
@@ -360,7 +410,7 @@ 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.2},
+  version      = {0.1.1.4},
   howpublished = {\url{https://github.com/ai-nikolai/mini-code-cli}},
   note         = {A no-bloat, dependency-light agent CLI for experimenting.}
 }

mini_code_cli-0.1.1.4/mini_code_cli/agent_files.py

@@ -0,0 +1,90 @@
+"""Agent-owned files kept in ``--allowed-dir/.mini``.
+
+Two opt-in features put a file the *agent* may read and write there, rather
+than in the session directory the loop owns:
+
+  * the **scratchpad** (``--scratchpad``): a free-form note file for thoughts,
+    plans and learnings, plus as many additional scratch files as the agent
+    wants to create;
+  * the **open plan** (``--plan-strategy open-plan``): a plan document the
+    agent maintains itself with the normal file tools.
+
+Both live under the same ``.mini`` directory as the skills folder and the
+latest-session pointer, so they are inside the ``--allowed-dir`` sandbox and
+the normal ``read_file`` / ``write_file`` / ``edit`` tools can reach them. The
+directory name is read from :mod:`mini_code_cli.persistence` at call time, so
+the test suite can redirect it globally (exactly like the session pointer).
+"""
+
+import os
+
+from . import persistence
+
+SCRATCHPAD_FILENAME = "SCRATCHPAD.md"
+OPEN_PLAN_FILENAME = "PLAN.md"
+
+_SCRATCHPAD_HEADER = """# Scratchpad
+
+This file belongs to the agent. It may read and write it freely and may create
+additional scratch files in the same directory. Use it for thoughts, plans,
+learnings and notes that should survive a compaction.
+"""
+
+_OPEN_PLAN_HEADER = """# Agent Plan
+
+This plan document belongs to the agent. Read it before continuing, keep it up
+to date as work progresses, and mark steps done or outstanding.
+"""
+
+
+def mini_dir(allowed_dir):
+    """The ``.mini`` directory inside ``allowed_dir`` (not created)."""
+    return os.path.join(os.path.abspath(allowed_dir), persistence.SESSION_DIRNAME)
+
+
+def scratchpad_path(allowed_dir):
+    """Path to the main scratch-pad file."""
+    return os.path.join(mini_dir(allowed_dir), SCRATCHPAD_FILENAME)
+
+
+def open_plan_path(allowed_dir):
+    """Path to the agent-authored plan document."""
+    return os.path.join(mini_dir(allowed_dir), OPEN_PLAN_FILENAME)
+
+
+def ensure_scratchpad(allowed_dir):
+    """Create the main scratch-pad file (and its directory) if missing."""
+    return _ensure_file(scratchpad_path(allowed_dir), _SCRATCHPAD_HEADER)
+
+
+def ensure_open_plan(allowed_dir):
+    """Create the agent plan document (and its directory) if missing."""
+    return _ensure_file(open_plan_path(allowed_dir), _OPEN_PLAN_HEADER)
+
+
+def read_text(path, limit=None):
+    """Read ``path`` as text, returning ``""`` when it cannot be read.
+
+    ``limit`` caps the returned characters (the open-plan re-injection after a
+    compaction should not be able to re-fill the context with the document).
+    """
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as handle:
+            text = handle.read()
+    except OSError:
+        return ""
+    if limit is not None and len(text) > limit:
+        return text[:limit] + "\n[... truncated ...]\n"
+    return text
+
+
+def _ensure_file(path, header):
+    """Best-effort create-with-header; never raises, always returns ``path``."""
+    try:
+        if not os.path.isfile(path):
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w", encoding="utf-8") as handle:
+                handle.write(header)
+    except OSError:
+        pass
+    return path