mini-code-cli 0.0.8.4__py3-none-any.whl → 0.1.0.0__py3-none-any.whl

mini_code_cli/agent_loop.py

@@ -16,6 +16,7 @@ smaller, focused modules so each concern is easy to read and test:
   * :mod:`mini_code_cli.runner`      -- running a tool with a wall-clock timeout.
   * :mod:`mini_code_cli.config`      -- shared default settings.
   * :mod:`mini_code_cli.subagents`   -- delegating a task to a sub-agent.
+  * :mod:`mini_code_cli.skills`      -- the ``.mini`` skills feature.
 
 For backward compatibility (and the test-suite) the most commonly imported
 helpers are re-exported from here, so ``from mini_code_cli.agent_loop import ...``
@@ -32,6 +33,7 @@ from . import tools
 from . import utils
 from . import ui
 from . import subagents
+from . import skills
 from . import plan as plan_utils
 from .config import (
     DEFAULT_CACHE_LOCATION,
@@ -116,14 +118,29 @@ def parse_args():
     parser.add_argument("--allowed-dir", type=str, default=".", help="Allowed directory for file operations, default='./'")
     parser.add_argument("-s", "--enable-shell", action="store_true", help="Allow shell execution. default= False")
     parser.add_argument("-g","--enable-subagents", action="store_true", help="Allow the agent to delegate work to sub-agents (exposed as extra tools). default= False")
+    parser.add_argument("--skills", action="store_true", help="Enable the skills feature: a local .mini directory (inside --allowed-dir) of skill.md files, skill sub-dirs, a high-level SKILLS.md summary, and executable Python scripts, exposed to the agent as list_skills/read_skill/create_skill/run_skill tools. default= False")
     parser.add_argument("--llm-timeout", type=int, default=DEFAULT_HTTP_TIMEOUT, help=f"HTTP timeout in seconds for LLM requests (reasoning models can be slow). default={DEFAULT_HTTP_TIMEOUT}")
     parser.add_argument("--tool-timeout", type=int, default=DEFAULT_TOOL_TIMEOUT, help=f"Timeout in seconds for a single tool call. default={DEFAULT_TOOL_TIMEOUT}")
     parser.add_argument("-p","--plan", action="store_true", help="Enable plan mode: the agent keeps a CURRENT_PLAN.md (its step-by-step plan, marked finished when the goal is done) and CURRENT_GOAL.md (the user's latest instruction) in the session directory. Also changes how history compaction works.")
 
+    parser.add_argument("--all", action="store_true", help="Enable: --plan, --subagents, --shell, --automode, --sudo")
+    parser.add_argument("--all-last", action="store_true", help="Enable: --plan, --subagents, --shell, --automode, --sudo, --load-last-session")
+
     # Output verbosity
     parser.add_argument("--verbose", action="store_true", help="Print the full, detailed output. Without it (default), only user/assistant turns, token usage and tool calls are shown.")
 
     args = parser.parse_args()
+
+    if args.all or args.all_last:
+        args.plan = True
+        args.enable_subagents = True
+        args.enable_shell = True
+        args.sudo = True
+        args.auto_mode = True
+    
+    if args.all_last:
+        args.load_last_session = True
+
     return args
 
 
@@ -154,6 +171,10 @@ def print_help(allowed_dir, server_url, args, unique_id, cache_dir, model_name):
         ui.console.emit(ui.console.style("Sub-agents:", bold=True, fg="cyan"))
         for sa in subagents.get_registry().values():
             ui.console.emit(f"  {sa.name:16} {sa.description}")
+    if args.enable_skills or args.verbose:
+        ui.console.emit(ui.console.style("Skills:", bold=True, fg="cyan"))
+        for name in skills.SKILL_TOOL_NAMES:
+            ui.console.emit(f"  {name:16} (from the local .mini directory)")
     ui.console.rule(char="═", fg="cyan")
 
 
@@ -285,6 +306,19 @@ class AgentSession:
             # real function.
             self.tools_dict[sa.name] = {"function": None, "description": sa.description, "subagent": True}
 
+        # Skills (opt-in via --skills). Each registered skill tool is exposed to
+        # the model as a normal tool, but they are all sandbox-safe: the .mini
+        # directory lives *inside* --allowed-dir and the tools never accept a
+        # path from the model -- skill / script names are validated as single
+        # path segments and resolved under the .mini root. So skills are exposed
+        # even in sessions without --enable-shell (run_skill only executes a
+        # named Python file, never a free-form shell command).
+        self.enable_skills = bool(getattr(args, "enable_skills", False))
+        if self.enable_skills:
+            self.skills_tools_dict = skills.get_skills_tools_dict(self.allowed_dir)
+            self.llm_tools.extend(skills.get_skills_tools(self.allowed_dir))
+            self.tools_dict.update(self.skills_tools_dict)
+
         # Token accounting for the whole session.
         self.token_stats = {
             "prompt_tokens": 0,
@@ -363,7 +397,11 @@ class AgentSession:
         if self.args.system_prompt:
             system_prompt = self.args.system_prompt
         else:
-            system_prompt = prompts.system_prompt(tools_dict=self.tools_dict, allowed_dir=self.allowed_dir, plan_mode=self.plan_mode)
+            system_prompt = prompts.system_prompt(
+                tools_dict=self.tools_dict, allowed_dir=self.allowed_dir,
+                plan_mode=self.plan_mode,
+                skills_dir=self.allowed_dir if self.enable_skills else None,
+            )
 
         messages = [{"role": "system", "content": system_prompt}]
 
@@ -619,20 +657,39 @@ class AgentSession:
         Appends ``initial_task`` as a user turn, then keeps stepping until the
         model makes no further tool calls (auto-mode). ``max_steps`` caps the
         number of model calls so a misbehaving sub-agent cannot loop forever.
+
+        The sub-agent records its work in its own cache dir: every step persists
+        history / recorder / usage into the child's own session folder, and it
+        seeds CURRENT_GOAL.md / CURRENT_PLAN.md (in plan mode) so each sub-session
+        is self-contained and easy to inspect or resume. A final record is left
+        even on a mid-run failure (the seeded goal is marked finished).
         """
         self.messages.append({"role": "user", "content": initial_task})
+        # Seed the goal up front so the child keeps a self-contained record in
+        # its own cache dir (a sub-agent always records a goal, independent of
+        # the parent's --plan flag). We use the child's own plan_manager here so
+        # nothing is written to the parent's session folder.
+        from .plan import PlanManager
+        child_plan = PlanManager(os.path.join(self.cache_dir, self.unique_id), enabled=True)
+        child_plan.write_goal(initial_task)
         steps = 0
-        while True:
-            should_continue = self._step()
+        try:
+            while True:
+                should_continue = self._step()
+                self._persist()
+                steps += 1
+                if max_steps and steps >= max_steps:
+                    self.console.note(
+                        f"Sub-agent reached max_steps ({max_steps}); stopping.", "warn")
+                    break
+                if not should_continue:
+                    break
+            return self._last_assistant_text()
+        finally:
+            # Leave a clean, finished record in the child's cache dir even on an
+            # error / early stop, so the sub-session is never left open.
+            child_plan.mark_finished()
             self._persist()
-            steps += 1
-            if max_steps and steps >= max_steps:
-                self.console.note(
-                    f"Sub-agent reached max_steps ({max_steps}); stopping.", "warn")
-                break
-            if not should_continue:
-                break
-        return self._last_assistant_text()
 
     def _last_assistant_text(self):
         """Return the content of the most recent assistant (non tool-call) turn."""

mini_code_cli/plan.py

@@ -6,14 +6,16 @@ active goal and the plan for reaching it:
 
   * ``CURRENT_GOAL.md``  -- the user's latest instruction / goal (verbatim).
   * ``CURRENT_PLAN.md``  -- the agent's current plan for that goal, followed by
-    a short running log (e.g. an entry recording when a goal was finished).
+    a short running log (e.g. an entry recording when a goal was set/changed,
+    and when it was finished).
 
 The plan document itself is authored by the agent (the system prompt tells it
 to, and it uses its ``write_file`` tool). This manager owns the parts the loop
 is responsible for -- seeding/reading the goal, reading the plan back so history
-compaction can re-inject it, and appending the "goal finished" log entry. It is
-deliberately free of any network or terminal dependency, and every method is a
-no-op when disabled, so it is trivial to unit-test in isolation.
+compaction can re-inject it, and appending the "goal finished" / goal-change log
+entries. It is deliberately free of any network or terminal dependency, and
+every method is a no-op when disabled, so it is trivial to unit-test in
+isolation.
 """
 
 import os
@@ -31,6 +33,11 @@ class PlanManager:
     ``history_{n}.json``). When ``enabled`` is False every method is a no-op, so
     callers can use the manager unconditionally and let the ``--plan`` flag
     decide whether anything actually happens.
+
+    ``session_dir`` is the session directory (``cache_dir/<unique_id>``) -- i.e.
+    the files always live in the *cache* dir, independent of ``--allowed-dir``.
+    The manager writes with plain ``open`` (not through the file tools), so the
+    records are created even when the allowed dir is a different location.
     """
 
     def __init__(self, session_dir, enabled=True, goal=None):
@@ -39,6 +46,10 @@ class PlanManager:
         # The last goal this manager was asked to record, so callers can tell a
         # new goal apart from the previous one. Kept in sync by write_goal().
         self.goal = goal
+        # The last goal (stripped) that was logged into CURRENT_PLAN.md, so
+        # write_goal can tell a genuine change apart from a re-stated goal and
+        # avoid spamming the plan with duplicate "goal updated" entries.
+        self._last_logged_goal = None
 
     # -- paths -------------------------------------------------------------
     @property
@@ -50,20 +61,55 @@ class PlanManager:
         return os.path.join(self.session_dir, GOAL_FILENAME)
 
     # -- writing -----------------------------------------------------------
+    def _append_plan_note(self, text):
+        """Append one dated line to CURRENT_PLAN.md (creating it if needed).
+
+        Shared by the goal-change log and ``mark_finished``. Best-effort and
+        never raises: a plan-tracking hiccup must never break the agent loop.
+        """
+        if not self.enabled:
+            return
+        try:
+            os.makedirs(self.session_dir, exist_ok=True)
+            if not os.path.exists(self.plan_path):
+                with open(self.plan_path, "w", encoding="utf-8") as f:
+                    f.write("# Current Plan\n\n")
+            with open(self.plan_path, "a", encoding="utf-8") as f:
+                f.write(text + "\n")
+        except OSError:
+            pass
+
     def write_goal(self, goal):
         """Persist the user's current goal / last instruction to CURRENT_GOAL.md.
 
         Overwrites any previous goal -- the file always reflects the *latest*
-        instruction. Best-effort and never raises: a plan-tracking hiccup must
-        never break the agent loop.
+        instruction. Also makes sure ``CURRENT_PLAN.md`` exists in the cache dir
+        (so both tracking files are present from the very first goal), and -- in
+        plan mode -- logs the goal into CURRENT_PLAN.md the *first* time it is
+        set and again whenever it changes, so the plan records goal pivots.
+        Best-effort and never raises.
         """
         if not self.enabled:
             return
+        stripped = (goal or "").strip()
         try:
             os.makedirs(self.session_dir, exist_ok=True)
+            # Ensure CURRENT_PLAN.md exists in the cache dir too, so the goal
+            # always has a companion plan file sitting next to it.
+            if not os.path.exists(self.plan_path):
+                with open(self.plan_path, "w", encoding="utf-8") as f:
+                    f.write("# Current Plan\n\n")
             with open(self.goal_path, "w", encoding="utf-8") as f:
                 f.write("# Current Goal\n\n")
-                f.write((goal or "").strip() + "\n")
+                f.write(stripped + "\n")
+            # Log the goal change into the plan -- but only on a genuine change
+            # (compared against the last goal actually logged), so re-stating the
+            # same goal on later turns does not spam the plan log.
+            if stripped and stripped != self._last_logged_goal:
+                verb = "Goal set to" if self._last_logged_goal is None else "Goal updated to"
+                stamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+                self._append_plan_note(f"- [{stamp}] {verb}: {stripped}")
+                self._last_logged_goal = stripped
             self.goal = goal
         except OSError:
             pass
@@ -82,16 +128,8 @@ class PlanManager:
         # never captured one itself, e.g. a one-shot --prompt preset), and only
         # then fall back to a generic description.
         goal = goal or self.goal or self._read(self.goal_path) or "current goal"
-        try:
-            os.makedirs(self.session_dir, exist_ok=True)
-            if not os.path.exists(self.plan_path):
-                with open(self.plan_path, "w", encoding="utf-8") as f:
-                    f.write("# Current Plan\n\n")
-            stamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-            with open(self.plan_path, "a", encoding="utf-8") as f:
-                f.write(f"\n- [{stamp}] Task finished: {goal}\n")
-        except OSError:
-            pass
+        stamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        self._append_plan_note(f"- [{stamp}] Task finished: {goal}")
 
     # -- reading -----------------------------------------------------------
     def read_plan(self):

mini_code_cli/prompts.py

@@ -1,5 +1,5 @@
 # System prompt defining available tools and compaction behavior
-def system_prompt(tools_dict=None, allowed_dir=None, plan_mode=False):
+def system_prompt(tools_dict=None, allowed_dir=None, plan_mode=False, skills_dir=None):
     """
     Takes a list of tool names and returns a system prompt string.
 
@@ -26,6 +26,10 @@ def system_prompt(tools_dict=None, allowed_dir=None, plan_mode=False):
     if allowed_dir:
         allowed_dir_prompt = f"\nThe path you are allowed to operate in is called: {allowed_dir}"
 
+    skills_prompt = ""
+    if skills_dir is not None:
+        skills_prompt = "\n" + skills_instructions(skills_dir)
+
     plan_mode_prompt = ""
     if plan_mode:
         plan_mode_prompt = "\n" + plan_instructions()
@@ -33,7 +37,7 @@ def system_prompt(tools_dict=None, allowed_dir=None, plan_mode=False):
     
     prompt = f"""
 {base_prompt}
-{tool_descriptions}{end_prompt}{allowed_dir_prompt}{plan_mode_prompt}
+{tool_descriptions}{end_prompt}{allowed_dir_prompt}{plan_mode_prompt}{skills_prompt}
 Important: Follow the user instruction. Do not create additional .md files (unless asked to do so). Do not create unit tests (unless asked to do so), etc.
 """
     return prompt.strip()
@@ -62,6 +66,36 @@ def plan_instructions():
         "easy to track and resume."
     )
 
+def skills_instructions(skills_dir):
+    """The extra system-prompt block when the skills feature is enabled.
+
+    Tells the agent it has a local ``.mini`` directory of reusable skills and
+    explains the four skill tools (see :mod:`mini_code_cli.skills`). ``skills_dir``
+    is the actual ``.mini`` path so the prompt can point at it concretely.
+    """
+    from . import skills as skills_mod
+    return (
+        "SKILLS MODE: You can work with reusable skills kept in the local "
+        f"`.mini` directory at: {skills_mod.skills_dir(skills_dir)}.\n"
+        "Each skill is a sub-directory containing a `skill.md` (what the skill is "
+        "/ how to use it) and optional executable Python helper scripts. There is "
+        "also a high-level `SKILLS.md` summary of all skills.\n"
+        "Use these tools to work with skills:\n"
+        "  * `list_skills`  - see which skills exist (name + one-line summary).\n"
+        "  * `read_skill`   - read a skill's `skill.md` by name, to learn how to "
+        "use it or which scripts it provides.\n"
+        "  * `create_skill` - create a new skill (its sub-directory and `skill.md`) "
+        "when you build a reusable capability. Give a clear, single-segment name "
+        "and a short summary. It is normal to then add Python helper scripts into "
+        "the skill's directory.\n"
+        "  * `run_skill`    - run one of a skill's Python scripts, passing any "
+        "command-line arguments via its `args`. Read the skill first to know "
+        "which script to run and what arguments it expects.\n"
+        "Prefer turning reusable helpers into skills (with a `skill.md` plus "
+        "scripts) so they can be reused later, rather than repeating one-off work.\n"
+    )
+
+
 def compaction_prompt(messages):
     """
     Takes a messages list and returns a compact prompt string summarizing the conversation.

mini_code_cli/skills.py

@@ -0,0 +1,365 @@
+"""mini_code_cli.skills -- the ``.mini`` *skills* feature.
+
+A *skill* is a small, reusable, self-describing capability the agent can load on
+demand, kept in a local ``.mini`` directory inside the allowed dir:
+
+    <allowed_dir>/.mini/
+        SKILLS.md                 # high-level summary of every skill
+        <skill-name>/
+            skill.md              # what the skill is / how to use it
+            <script>.py           # optional executable Python helper(s)
+
+The agent "works with skills" through four tools (only present when ``--skills``
+is enabled):
+
+  * ``list_skills``  -- what skills exist (names + one-line summaries).
+  * ``read_skill``   -- read a single skill's ``skill.md`` by name.
+  * ``create_skill`` -- create a new skill (its dir + ``skill.md``); this also
+                        refreshes the high-level ``SKILLS.md`` summary.
+  * ``run_skill``    -- execute one of a skill's Python scripts, with optional
+                        command-line args.
+
+Names are sandboxed *by construction*: skill / script names are validated to be
+a single safe path segment and then joined under the known ``.mini`` root inside
+the allowed dir, so a skill tool can never escape ``--allowed-dir``. A final
+``realpath`` containment check enforces that anyway.
+"""
+
+import os
+import sys
+import shlex
+import shutil
+import subprocess
+import functools
+
+# Default timeout (seconds) for a script run via run_skill.
+DEFAULT_TOOL_TIMEOUT = 120
+
+# Layout constants. Keeping them here (and re-exported) means prompts.py and the
+# agent loop can refer to the same names rather than hard-coding them twice.
+SKILLS_DIRNAME = ".mini"
+SUMMARY_FILENAME = "SKILLS.md"
+SKILL_FILENAME = "skill.md"
+SCRIPT_SUFFIX = ".py"
+
+# The tool names this feature contributes to the agent (used by the loop to
+# register them and by the sandbox/help wiring).
+SKILL_TOOL_NAMES = ("list_skills", "read_skill", "create_skill", "run_skill")
+
+
+# -- paths -----------------------------------------------------------------
+def skills_dir(allowed_dir):
+    """The ``.mini`` directory for ``allowed_dir``."""
+    return os.path.join(allowed_dir, SKILLS_DIRNAME)
+
+
+def summary_path(allowed_dir):
+    """Path to the high-level ``SKILLS.md`` summary."""
+    return os.path.join(skills_dir(allowed_dir), SUMMARY_FILENAME)
+
+
+def skill_dir(allowed_dir, skill_name):
+    """Path to a single skill's sub-directory."""
+    return os.path.join(skills_dir(allowed_dir), skill_name)
+
+
+def skill_md_path(allowed_dir, skill_name):
+    """Path to a skill's ``skill.md``."""
+    return os.path.join(skill_dir(allowed_dir, skill_name), SKILL_FILENAME)
+
+
+# -- name safety -----------------------------------------------------------
+def _safe_name(name, what="name"):
+    """Return ``name`` if it is a safe single path segment, else ``None``.
+
+    Rejects empty names, absolute paths, any path separator and the ``.`` /
+    ``..`` special segments, so skill / script names cannot traverse out of the
+    ``.mini`` root or address sibling directories. Best-effort: never raises.
+    """
+    if name is None:
+        return None
+    name = str(name).strip()
+    if not name:
+        return None
+    if name in (".", ".."):
+        return None
+    # Any separator at all means "this is trying to be a path" -> refuse.
+    # Reject any path separator on either platform (plus a bare backslash), so
+    # a name can never contain a directory component -- it cannot traverse.
+    # Any separator (on either platform) plus a bare backslash means
+    # "this is trying to be a path" -> refuse, so a name can never hold a
+    # directory component and cannot traverse.
+    if any(sep in name for sep in (os.sep, "\\", "/")):
+        return None
+    return name
+
+
+# -- discovery -------------------------------------------------------------
+def _list_skill_names(allowed_dir):
+    """Return the sorted names of skills (dirs holding a ``skill.md``)."""
+    sd = skills_dir(allowed_dir)
+    if not os.path.isdir(sd):
+        return []
+    out = []
+    for entry in sorted(os.listdir(sd)):
+        if os.path.isdir(os.path.join(sd, entry)) and \
+                os.path.isfile(os.path.join(sd, entry, SKILL_FILENAME)):
+            out.append(entry)
+    return out
+
+
+def list_scripts(allowed_dir, skill_name):
+    """Return the executable Python script names (without ``.py``) in a skill."""
+    safe = _safe_name(skill_name)
+    if not safe:
+        return []
+    base = skill_dir(allowed_dir, safe)
+    if not os.path.isdir(base):
+        return []
+    out = []
+    for entry in sorted(os.listdir(base)):
+        if entry.endswith(SCRIPT_SUFFIX):
+            out.append(entry[: -len(SCRIPT_SUFFIX)])
+    return out
+
+
+def ensure_skills_dir(allowed_dir):
+    """Create ``.mini`` and a skeleton ``SKILLS.md`` if they do not exist yet.
+
+    Best-effort and never raises: a skills hiccup must never break the loop.
+    """
+    try:
+        sd = skills_dir(allowed_dir)
+        os.makedirs(sd, exist_ok=True)
+        if not os.path.exists(summary_path(allowed_dir)):
+            _write_summary(allowed_dir, [])
+    except OSError:
+        pass
+
+
+def _skill_metadata(allowed_dir, skill_name):
+    """Return ``(title, description)`` for a skill read from its ``skill.md``.
+
+    ``description`` is the ``Summary:`` line if the skill has one, else the first
+    non-heading line of the file. ``title`` is the first ``#`` heading, else the
+    skill name. Best-effort: a missing/unreadable file yields (name, "").
+    """
+    path = skill_md_path(allowed_dir, skill_name)
+    if not os.path.isfile(path):
+        return skill_name, ""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            content = f.read()
+    except OSError:
+        return skill_name, ""
+
+    description = ""
+    title = skill_name
+    for line in content.splitlines():
+        stripped = line.strip()
+        if not title and stripped.startswith("#"):
+            title = stripped.lstrip("#").strip() or skill_name
+            continue
+        if stripped.lower().startswith("summary:"):
+            description = stripped.split(":", 1)[1].strip()
+            break
+        if not stripped or stripped.startswith("#"):
+            continue
+        description = stripped
+        break
+    return (title or skill_name), description
+
+
+# -- tools -----------------------------------------------------------------
+def list_skills(allowed_dir):
+    """List available skills (name + one-line summary). Creates ``.mini`` first.
+
+    No parameters from the model (``allowed_dir`` is bound at wiring time).
+    """
+    ensure_skills_dir(allowed_dir)
+    skills = _list_skill_names(allowed_dir)
+    # Keep the high-level SKILLS.md summary in sync with what is on disk (e.g.
+    # scripts dropped into a skill after it was created), so list_skills always
+    # reflects the current state.
+    if skills:
+        _write_summary(allowed_dir, skills)
+    if not skills:
+        return "No skills yet. Use create_skill to add one."
+    lines = ["Available skills:", ""]
+    for name in skills:
+        _title, desc = _skill_metadata(allowed_dir, name)
+        lines.append(f"- {name}: {desc}")
+    return "\n".join(lines)
+
+
+def read_skill(allowed_dir, skill_name):
+    """Return the contents of a skill's ``skill.md`` by name.
+
+    If the skill does not exist, returns an error listing the available skills
+    so the agent can recover.
+    """
+    safe = _safe_name(skill_name)
+    if not safe:
+        return "Error: invalid skill name."
+    path = skill_md_path(allowed_dir, safe)
+    if not os.path.isfile(path):
+        available = _list_skill_names(allowed_dir)
+        listing = ", ".join(available) if available else "none"
+        return f"Error: no skill named {skill_name!r}. Available skills: {listing}."
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read()
+    except OSError as e:
+        return f"Error: {e}"
+
+
+def create_skill(allowed_dir, skill_name, description, title=None, overwrite=False):
+    """Create a new skill: its sub-directory and ``skill.md``.
+
+    Refreshes the high-level ``SKILLS.md`` summary afterwards so the new skill
+    shows up in list_skills. Refuses to clobber an existing skill unless
+    ``overwrite`` is set. Best-effort: never raises, returns an Error string.
+    """
+    safe = _safe_name(skill_name)
+    if not safe:
+        return "Error: invalid skill name. Use a short, single-segment name."
+    if not description:
+        return "Error: a description is required."
+
+    sdir = skill_dir(allowed_dir, safe)
+    mpath = skill_md_path(allowed_dir, safe)
+    if os.path.exists(mpath) and not overwrite:
+        return (f"Error: skill {safe!r} already exists (use overwrite to replace "
+                f"it).")
+
+    try:
+        os.makedirs(sdir, exist_ok=True)
+        with open(mpath, "w", encoding="utf-8") as f:
+            f.write(_skill_md_template(title or safe, description))
+        _write_summary(allowed_dir, _list_skill_names(allowed_dir))
+        return f"Created skill {safe!r} at {mpath}"
+    except OSError as e:
+        return f"Error: {e}"
+
+
+def delete_skill(allowed_dir, skill_name):
+    """Delete a skill's sub-directory (and drop it from SKILLS.md).
+
+    Kept minimal and only surfaced if ever wanted as a tool; best-effort.
+    """
+    safe = _safe_name(skill_name)
+    if not safe:
+        return "Error: invalid skill name."
+    sdir = skill_dir(allowed_dir, safe)
+    if not os.path.isdir(sdir):
+        return f"Error: no skill named {skill_name!r}."
+    try:
+        shutil.rmtree(sdir)
+        _write_summary(allowed_dir, _list_skill_names(allowed_dir))
+        return f"Deleted skill {safe!r}."
+    except OSError as e:
+        return f"Error: {e}"
+
+
+def run_skill(allowed_dir, skill_name, script_name, args=None):
+    """Execute one of a skill's Python scripts and return its output.
+
+    ``args`` is an optional string of command-line arguments, split with
+    :func:`shlex.split` and passed as ``argv`` (never through a shell, so there
+    is no shell-injection surface). The script is run with the same interpreter
+    that runs mini-code (``sys.executable``). The script path is resolved under
+    the skill's directory and checked to stay inside it.
+    """
+    safe = _safe_name(skill_name)
+    script = _safe_name(script_name)
+    if not safe or not script:
+        return "Error: invalid skill or script name."
+    if not script.endswith(SCRIPT_SUFFIX):
+        script += SCRIPT_SUFFIX
+
+    base = os.path.realpath(skill_dir(allowed_dir, safe))
+    script_path = os.path.realpath(os.path.join(base, script))
+    # Containment: the script must live directly inside the skill dir.
+    if os.path.dirname(script_path) != base:
+        return "Error: script path escapes the skill directory."
+    if not os.path.isfile(script_path):
+        available = ", ".join(list_scripts(allowed_dir, safe)) or "none"
+        return (f"Error: no script {script!r} in skill {safe!r}. "
+                f"Available scripts: {available}.")
+
+    argv = shlex.split(args) if args else []
+    cmd = [sys.executable, script_path] + argv
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True,
+                                timeout=DEFAULT_TOOL_TIMEOUT, check=False)
+    except Exception as e:
+        return f"Error: {e}"
+    out = result.stdout
+    if result.stderr:
+        out += "\nSTDERR:\n" + result.stderr
+    return out
+
+
+# -- summary ---------------------------------------------------------------
+def _skill_md_template(title, description):
+    return (
+        f"# {title}\n\n"
+        f"Summary: {description}\n\n"
+        "## How to use\n"
+        f"{description}\n\n"
+        "## Scripts\n"
+        "- (none yet)\n"
+    )
+
+
+def _write_summary(allowed_dir, skill_names):
+    """Write the high-level ``SKILLS.md`` summary from the given skill names."""
+    lines = [
+        "# Skills",
+        "",
+        "This is the high-level summary of the skills kept in the local "
+        "`.mini` directory. Each skill lives in its own sub-directory with a "
+        "`skill.md` (what it is / how to use it) and optional executable "
+        "Python scripts. Use `list_skills` / `read_skill` to consult them, "
+        "`create_skill` to add one, and `run_skill` to run a skill's scripts.",
+        "",
+    ]
+    if not skill_names:
+        lines += ["No skills yet.", ""]
+    for name in skill_names:
+        _title, desc = _skill_metadata(allowed_dir, name)
+        lines.append(f"## {name}")
+        lines.append(desc or "(no summary)")
+        scripts = list_scripts(allowed_dir, name)
+        if scripts:
+            lines.append("")
+            lines.append(f"Scripts: {', '.join(scripts)}")
+        lines.append("")
+    try:
+        with open(summary_path(allowed_dir), "w", encoding="utf-8") as f:
+            f.write("\n".join(lines))
+    except OSError:
+        pass
+
+
+# -- wiring (tool schemas + bound functions) -------------------------------
+def _skill_functions(allowed_dir):
+    """{name: functools.partial} for the four skill tools, allowed_dir bound."""
+    return {
+        "list_skills": functools.partial(list_skills, allowed_dir),
+        "read_skill": functools.partial(read_skill, allowed_dir),
+        "create_skill": functools.partial(create_skill, allowed_dir),
+        "run_skill": functools.partial(run_skill, allowed_dir),
+    }
+
+
+def get_skills_tools(allowed_dir):
+    """Return the OpenAI tool schemas for the four skill tools."""
+    from . import tools
+    return tools.util_get_tools(functions=_skill_functions(allowed_dir))
+
+
+def get_skills_tools_dict(allowed_dir):
+    """Return {name: bound-function} for the four skill tools."""
+    from . import tools
+    return tools.util_get_tools_dict(functions=_skill_functions(allowed_dir))

mini_code_cli/subagents/builtin.py

@@ -1,8 +1,11 @@
-"""mini_code_cli.subagents.builtin -- two worked example sub-agents.
+"""mini_code_cli.subagents.builtin -- the built-in sub-agents.
 
 These are registered on import (see :mod:`mini_code_cli.subagents`). They double
 as documentation for how to build your own: a sub-agent is just a small class
-configuring a name, a description, and a few knobs.
+configuring a name, a description, a set of tools, and a few knobs. Each one
+targets a specific kind of work -- its ``system_prompt`` overrides add a short,
+task-specific preamble on top of the shared base prompt so the nested agent
+knows exactly what "done" looks like for this kind of task.
 """
 from .base import SubAgent
 from . import register
@@ -74,6 +77,95 @@ class PlanSubAgent(SubAgent):
         )
 
 
-# Register the built-in examples.
+class SoftwareEngineeringSubAgent(SubAgent):
+    """Implement, edit, refactor or test code in a project.
+
+    This is the "do the actual engineering" sub-agent. It can read and write
+    files and run shell commands, so it is meant for real coding work: writing a
+    new module, refactoring, wiring up a fix, running the tests / a build to
+    check it. It is given a task-specific system prompt that biases it toward
+    producing working, tested, minimal changes rather than exploratory writing.
+
+    Because it can run shell commands it should only be used in sessions where
+    the caller is comfortable with that; the parent's sandbox / shell-safety
+    rules still apply.
+    """
+
+    name = "software_engineer"
+    description = (
+        "Software-engineering sub-agent: write, edit, refactor, fix or test code "
+        "in the project. It can read/write files and run shell commands (tests, "
+        "builds, etc.) to verify the work. Hands back a summary of the changes."
+    )
+    tools = ["read_file", "write_file", "grep", "glob", "run_shell_command"]
+    enable_shell = True
+    max_steps = 20
+
+    def system_prompt(self, task, parent):
+        base = super().system_prompt(task, parent)
+        return base + (
+            "\n\n---\nYou are the SOFTWARE ENGINEERING sub-agent: you write and "
+            "modify code to get a real task done. Follow these guidelines:\n"
+            "* Understand the relevant code before editing: read the files and "
+            "use grep/glob to find what you need. Prefer small, targeted edits over "
+            "rewriting large files.\n"
+            "* Keep changes minimal and focused on the task; do not touch unrelated "
+            "code.\n"
+            "* Make edits that are syntactically valid and consistent with the "
+            "existing style (imports, formatting, naming).\n"
+            "* When it makes sense, verify your work: run the project's tests, a "
+            "build, a linter or the code itself with run_shell_command, and use "
+            "the output to fix problems. Do not claim something works without "
+            "checking when you are able to check.\n"
+            "* If a task is ambiguous, make a sensible, minimal choice and state "
+            "it. Note any trade-offs or follow-ups.\n"
+            "When finished, write a concise summary of what you changed, why, and "
+            "how you verified it (including any test/build commands you ran and "
+            "their results) to report.md."
+        )
+
+
+class GenericSubAgent(SubAgent):
+    """A general-purpose helper for tasks that do not fit a narrower agent.
+
+    This is the catch-all sub-agent: it has the full set of read/write tools and
+    may run shell commands, so it can handle "everything else" -- formatting a
+    document, organising files, drafting text, running a quick script, or any
+    one-off task the main agent wants to farm out. Its system prompt is a light,
+    task-agnostic scaffold that works for a broad range of requests.
+    """
+
+    name = "generic"
+    description = (
+        "General-purpose sub-agent for tasks that do not fit a more specialised "
+        "one. It can read/write files and run shell commands, so it suits most "
+        "one-off jobs. Hands back a summary of what it did."
+    )
+    tools = ["read_file", "write_file", "grep", "glob", "run_shell_command"]
+    enable_shell = True
+    max_steps = 12
+
+    def system_prompt(self, task, parent):
+        base = super().system_prompt(task, parent)
+        return base + (
+            "\n\n---\nYou are a GENERAL-PURPOSE sub-agent: a capable, careful "
+            "helper handed a single task. Follow these guidelines:\n"
+            "* Start by making sure you understand the task. If anything is "
+            "unclear, make a sensible, clearly-stated assumption and proceed -- "
+            "do not stall.\n"
+            "* Use the tools available to you: read before you write, and prefer "
+            "small, correct steps over large, risky ones.\n"
+            "* Prefer doing the task for real (editing files, running commands) "
+            "over merely describing how it could be done.\n"
+            "* If you run commands or make edits that could fail, check the "
+            "result and adapt.\n"
+            "When finished, write a concise summary of what you did and any "
+            "decisions or follow-ups to report.md."
+        )
+
+
+# Register the built-in sub-agents.
 register(ResearchSubAgent())
 register(PlanSubAgent())
+register(SoftwareEngineeringSubAgent())
+register(GenericSubAgent())

mini_code_cli/tools.py

@@ -1,8 +1,18 @@
+"""mini_code_cli.tools -- the tool functions the agent loop can expose to the LLM.
+
+The plain functions in this module (``read_file``, ``grep``, ...) are the
+default tools. They can be discovered automatically (see
+:func:`util_get_tools` / :func:`util_get_tools_dict`). A caller may also pass an
+explicit ``functions`` mapping so another feature (e.g. :mod:`mini_code_cli.skills`,
+whose tools already have ``allowed_dir`` bound) can reuse the schema/formatting.
+"""
 import glob as glob_module
 import subprocess
 import urllib.parse
 import urllib.request
 import json
+import inspect
+import functools
 
 # Default timeout (seconds) for a single tool invocation. Mirrors the CLI's
 # --tool-timeout default so a tool that is slow/hangs gets aborted.
@@ -144,43 +154,96 @@ def run_shell_command(command, timeout=DEFAULT_TOOL_TIMEOUT, *args, **kwargs):
         return f"Error: {e}"
 
 
-def util_get_tools(allowed_tools=None, forbidden_tools=None):
-    """Return a JSON string describing all tool functions in this file for LLM usage."""
-    import inspect
+def _local_function_names():
+    """Names of the real tool functions defined in this module (not util_/_)."""
+    return [name for name, obj in globals().items()
+            if callable(obj) and obj.__module__ == __name__
+            and not name.startswith('util_') and not name.startswith("_")]
+
+
+def _param_type(annotation):
+    """Map a type annotation to an OpenAI-schema type string."""
+    param_type = str(annotation) if annotation != inspect.Parameter.empty else "string"
+    if 'int' in param_type.lower() or 'integer' in param_type.lower():
+        return "integer"
+    if 'float' in param_type.lower() or 'number' in param_type.lower():
+        return "number"
+    if 'bool' in param_type.lower():
+        return "boolean"
+    if 'list' in param_type.lower() or 'array' in param_type.lower():
+        return "array"
+    return "string"
+
+
+def _schema_params(func):
+    """Return ``(properties, required)`` for a tool callable's signature.
+
+    Handles both plain module functions and :func:`functools.partial` objects
+    (used by skills, which bind ``allowed_dir`` up front): parameters that are
+    already bound on a partial are omitted from the schema, and remaining
+    non-default parameters are marked required. ``*args`` / ``**kwargs``
+    catch-alls are always skipped.
+    """
+    if isinstance(func, functools.partial):
+        underlying = func.func
+        bound_kwargs = dict(func.keywords or {})
+        bound_positional = list(func.args)
+    else:
+        underlying = func
+        bound_kwargs = {}
+        bound_positional = []
+
+    sig = inspect.signature(underlying)
+    # Bind leading positional args (in signature order) to the partial's
+    # positional args, so a positional bound arg hides the right parameter.
+    positional_names = [
+        pn for pn, p in sig.parameters.items()
+        if p.kind not in (inspect.Parameter.VAR_POSITIONAL,
+                          inspect.Parameter.VAR_KEYWORD)
+    ]
+    positional_bound = {}
+    for i, pname in enumerate(positional_names):
+        if i < len(bound_positional):
+            positional_bound[pname] = bound_positional[i]
+
+    properties = {}
+    required = []
+    for param_name, param in sig.parameters.items():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL,
+                          inspect.Parameter.VAR_KEYWORD):
+            continue
+        if param_name in bound_kwargs or param_name in positional_bound:
+            # Already bound on the partial -- the LLM must not supply it.
+            continue
+        param_type = _param_type(param.annotation)
+        properties[param_name] = {"type": param_type}
+        if param.default == inspect.Parameter.empty:
+            required.append(param_name)
+    return properties, required
+
+
+def util_get_tools(allowed_tools=None, forbidden_tools=None, functions=None):
+    """Return a JSON string describing tool functions for LLM usage.
+
+    By default scans this module's own tool functions. When ``functions`` is a
+    {name: callable} mapping, those are described instead (in ``functions``
+    order) -- letting other features (e.g. skills, with ``allowed_dir`` already
+    bound) contribute their own tools while reusing this formatting.
+    """
     tools = []
-    func_names = [name for name, obj in globals().items() if callable(obj) and obj.__module__ == __name__ and not name.startswith('util_') and not name.startswith("_")]
-    
+
+    if functions:
+        items = list(functions.items())
+    else:
+        items = [(name, globals()[name]) for name in _local_function_names()]
+
     if allowed_tools:
-        func_names = [name for name in func_names if name in allowed_tools]
+        items = [(n, f) for n, f in items if n in allowed_tools]
     if forbidden_tools:
-        func_names = [name for name in func_names if name not in forbidden_tools]
-
-    for name in func_names:
-        func = globals()[name]
-        sig = inspect.signature(func)
-        parameters = {}
-        required = []
-        for param_name, param in sig.parameters.items():
-            # Skip *args and **kwargs: they are catch-alls, not real inputs the
-            # LLM should (or can) supply, so they must not appear in the schema.
-            if param.kind in (inspect.Parameter.VAR_POSITIONAL,
-                              inspect.Parameter.VAR_KEYWORD):
-                continue
-            param_type = str(param.annotation) if param.annotation != inspect.Parameter.empty else "string"
-            # Simplify common types
-            if 'int' in param_type.lower() or 'integer' in param_type.lower():
-                param_type = "integer"
-            elif 'float' in param_type.lower() or 'number' in param_type.lower():
-                param_type = "number"
-            elif 'bool' in param_type.lower():
-                param_type = "boolean"
-            elif 'list' in param_type.lower() or 'array' in param_type.lower():
-                param_type = "array"
-            else:
-                param_type = "string"
-            parameters[param_name] = {"type": param_type}
-            if param.default == inspect.Parameter.empty:
-                required.append(param_name)
+        items = [(n, f) for n, f in items if n not in forbidden_tools]
+
+    for name, func in items:
+        properties, required = _schema_params(func)
         tool = {
             "type": "function",
             "function": {
@@ -188,7 +251,7 @@ def util_get_tools(allowed_tools=None, forbidden_tools=None):
                 "description": func.__doc__ if func.__doc__ else f"Function {name}",
                 "parameters": {
                     "type": "object",
-                    "properties": parameters,
+                    "properties": properties,
                     "required": required
                 }
             }
@@ -197,25 +260,33 @@ def util_get_tools(allowed_tools=None, forbidden_tools=None):
     return tools
 
 
-def util_get_tools_dict(allowed_tools=None, forbidden_tools=None):
-    """Return a dictionary mapping tool names to their function objects."""
+def util_get_tools_dict(allowed_tools=None, forbidden_tools=None, functions=None):
+    """Return a dictionary mapping tool names to their function objects.
+
+    ``functions`` is an optional {name: callable} mapping used in place of this
+    module's own functions (see :func:`util_get_tools`)."""
     result = {}
-    func_names = [name for name, obj in globals().items() if callable(obj) and obj.__module__ == __name__ and not name.startswith('util_') and not name.startswith("_")]
+
+    if functions:
+        items = list(functions.items())
+    else:
+        items = [(name, globals()[name]) for name in _local_function_names()]
+
     if allowed_tools:
-        func_names = [name for name in func_names if name in allowed_tools]
+        items = [(n, f) for n, f in items if n in allowed_tools]
     if forbidden_tools:
-        func_names = [name for name in func_names if name not in forbidden_tools]
+        items = [(n, f) for n, f in items if n not in forbidden_tools]
 
-    for name in func_names:
-        func = globals()[name]
+    for name, func in items:
         desc = func.__doc__ if func.__doc__ else f"Function {name}"
         result[name] = {"function": func, "description": desc}
     return result
 
+
 shell_tools = [
     "run_shell_command"
 ]
 
-if __name__=="__main__":
+if __name__ == "__main__":
     print(util_get_tools())
-    # print(json.dumps(tools_dict, indent=4))
+    # print(json.dumps(tools_dict, indent=4))

{mini_code_cli-0.0.8.4.dist-info → mini_code_cli-0.1.0.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mini-code-cli
-Version: 0.0.8.4
-Summary: Mini Coding CLI.
+Version: 0.1.0.0
+Summary: Mini Coding Agent. Allows you to easily experiment with a small coding agent.
 Author-email: Nikolai Rozanov <nikolai.rozanov@gmail.com>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE
                                Version 3, 19 November 2007
@@ -700,6 +700,9 @@ mini-code --url "https://api.deepseek.com" --model "deepseek-v4-flash"
 ```bash
 mini-code --enable-shell --auto-mode
 mini-code -s -a --sudo
+mini-code -s -a -p -g -l --sudo #plan, previous session, subagents (#or short-hand the next commands)
+mini-code --all
+mini-code --all-last
 ```
 
 4. Advanced usage:

{mini_code_cli-0.0.8.4.dist-info → mini_code_cli-0.1.0.0.dist-info}/RECORD

@@ -1,22 +1,23 @@
 mini_code_cli/__init__.py,sha256=iNgHmKSHOuH99obGjnUMoS2JP4Gw4AOrIfu68EYaZQM,77
-mini_code_cli/agent_loop.py,sha256=RMr3VOyUc_zPEOW629MDVoj9dZ1mGDLywWF4Bcmq9j8,52671
+mini_code_cli/agent_loop.py,sha256=DnoHKv9hsB7a9ibdvbt3HxfsdASpw8N1Gw2dTLZFI9g,55999
 mini_code_cli/config.py,sha256=AvzDZAKynQbuj5lcTtL-DcUwhyLa99QmNrLK6fYpdOA,814
 mini_code_cli/permissions.py,sha256=uQpQlUtQyVICpjUqdh9QQ_mgl51hZrGLHJzQR9vG124,2017
 mini_code_cli/persistence.py,sha256=L47NhXs6R54KETd8R17oGGxCXNEf7bjmvlwAJqtspLI,9944
-mini_code_cli/plan.py,sha256=uvbs8BcXKFO8Melhjt2R3ZA8JZJ2n4ELsMI6UKeZVyo,4819
-mini_code_cli/prompts.py,sha256=JRrRWwHc3PGCq1efAloQ_mXzGuYCSUJKUAJz9pp3UxQ,3565
+mini_code_cli/plan.py,sha256=M5WZQuiN8F_K7zyWIrU_5R9L8dcN9k8iYouXzfL_KOs,6985
+mini_code_cli/prompts.py,sha256=X05Krwf9X46WinbHzHj8WYq4RTnO56KZpMiRYS2CGLw,5452
 mini_code_cli/runner.py,sha256=oYUAzbQOrkakuR2uT1OnIrruh_XJYWEDzKpM09T4Zp0,1927
 mini_code_cli/sandbox.py,sha256=t7xS_AIpE8fbo5kj9zbUFbfEaAnq6iUE7plQcn6-uAk,2128
 mini_code_cli/shell_safety_utils.py,sha256=5E126vGnG7iIuTZe_R5JrxB_zxZpMKGe_pilz_Z2r4w,5551
-mini_code_cli/tools.py,sha256=66hQUyDC_3HCC6l4ua_f1YwFL0FcJ98G5X8wx7h-ojQ,8660
+mini_code_cli/skills.py,sha256=baaz0RkPQ-OgWWwH5sHsKBmJdR430yT4HK3VLX0_88Y,13704
+mini_code_cli/tools.py,sha256=bW1zYyIj6OFp5TIcg5DCwheN-4xI1LQmDOQaHIfRV7M,10998
 mini_code_cli/ui.py,sha256=AUwn0OFt3yFx397-V8kYuidseCBxFHgO1KWDKrlLCOU,29371
 mini_code_cli/utils.py,sha256=ffUAIisO8_h7VvlwAOLhdoNSAIdssGdtQHXm-i8bcLE,4620
 mini_code_cli/subagents/__init__.py,sha256=3fgcwY0pNq5iW29OxLPtSA3H5IKXhl2LUhwbBjLUDuU,1884
 mini_code_cli/subagents/base.py,sha256=bhZEENoTVjebfqaEKS7uPWeU0SwQWFN3BD40EtziPbg,12660
-mini_code_cli/subagents/builtin.py,sha256=bUCXV_FzymjegKrYF2me2GPY7dBs8PbomVSkHIaWVSQ,2891
-mini_code_cli-0.0.8.4.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
-mini_code_cli-0.0.8.4.dist-info/METADATA,sha256=OXsCt9J7CvmBnkH6gqybMemXnEtydd0gWvrGffytG-Q,52092
-mini_code_cli-0.0.8.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-mini_code_cli-0.0.8.4.dist-info/entry_points.txt,sha256=MwDp5UbXpI7wodSmOSYL8_nKutnBiyp96ZDDtaX7x14,60
-mini_code_cli-0.0.8.4.dist-info/top_level.txt,sha256=3Hb6PpNkJYXvzDKXuuFJRvzCdsTRh0TuRWz-ScJ6qV0,14
-mini_code_cli-0.0.8.4.dist-info/RECORD,,
+mini_code_cli/subagents/builtin.py,sha256=ENzuooXIylzfZZ8uYkZmdxgCrCQ4pdbfrOONkBdGSPg,7598
+mini_code_cli-0.1.0.0.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+mini_code_cli-0.1.0.0.dist-info/METADATA,sha256=iUqH7NzuQqmIetQQjA5Re6-sADvq7JD_iGQDKehWqpQ,52292
+mini_code_cli-0.1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mini_code_cli-0.1.0.0.dist-info/entry_points.txt,sha256=MwDp5UbXpI7wodSmOSYL8_nKutnBiyp96ZDDtaX7x14,60
+mini_code_cli-0.1.0.0.dist-info/top_level.txt,sha256=3Hb6PpNkJYXvzDKXuuFJRvzCdsTRh0TuRWz-ScJ6qV0,14
+mini_code_cli-0.1.0.0.dist-info/RECORD,,