minima-cli 0.4.9__py3-none-any.whl

minima_harness/tools/builtin.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from minima_harness.agent.tools import AgentTool
+from minima_harness.tools.bash import bash_tool
+from minima_harness.tools.edit import edit_tool
+from minima_harness.tools.find import find_tool
+from minima_harness.tools.grep import grep_tool
+from minima_harness.tools.ls import ls_tool
+from minima_harness.tools.read import read_tool
+from minima_harness.tools.write import write_tool
+
+
+def default_toolset() -> list[AgentTool]:
+    """PI's seven default coding tools, in a stable order."""
+    return [
+        read_tool(),
+        write_tool(),
+        edit_tool(),
+        bash_tool(),
+        grep_tool(),
+        find_tool(),
+        ls_tool(),
+    ]

minima_harness/tools/edit.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from minima_harness.agent.tools import AgentTool, ToolResult, error_result
+from minima_harness.ai.types import TextContent
+
+
+class EditParams(BaseModel):
+    path: str
+    old_string: str
+    new_string: str
+    replace_all: bool = False
+
+
+async def _execute(tool_call_id: str, params, signal, on_update) -> ToolResult:  # noqa: ANN001
+    assert isinstance(params, EditParams)
+    p = Path(params.path).expanduser()
+    if not p.exists():
+        return error_result(f"edit: no such file: {p}")
+    text = p.read_text(encoding="utf-8")
+    count = text.count(params.old_string)
+    if count == 0:
+        return error_result(f"edit: old_string not found in {p}")
+    if count > 1 and not params.replace_all:
+        return error_result(
+            f"edit: old_string matches {count} times in {p}; "
+            "add more surrounding context or set replace_all=True"
+        )
+    new = text.replace(params.old_string, params.new_string)
+    p.write_text(new, encoding="utf-8")
+    replaced = count if params.replace_all else 1
+    return ToolResult(
+        content=[TextContent(text=f"edited {p}: {replaced} replacement(s)")],
+        details={"replacements": replaced},
+    )
+
+
+def edit_tool() -> AgentTool:
+    return AgentTool(
+        name="edit",
+        description=(
+            "Replace an exact string in a file. Errors if old_string is absent or "
+            "(without replace_all) appears more than once — add context to disambiguate."
+        ),
+        parameters=EditParams,
+        execute=_execute,
+    )

minima_harness/tools/find.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import glob
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from minima_harness.agent.tools import AgentTool, ToolResult
+from minima_harness.ai.types import TextContent
+
+
+class FindParams(BaseModel):
+    pattern: str
+    path: str = "."
+
+
+async def _execute(tool_call_id: str, params, signal, on_update) -> ToolResult:  # noqa: ANN001
+    assert isinstance(params, FindParams)
+    root = Path(params.path).expanduser()
+    pat = str(root / params.pattern)
+    matches = sorted(glob.glob(pat, recursive=True))
+    body = "\n".join(matches) if matches else "(no matches)"
+    return ToolResult(
+        content=[TextContent(text=body)],
+        details={"count": len(matches)},
+    )
+
+
+def find_tool() -> AgentTool:
+    return AgentTool(
+        name="find",
+        description=(
+            "Find files matching a glob pattern (supports ** for recursive search). "
+            "Returns file paths only."
+        ),
+        parameters=FindParams,
+        execute=_execute,
+    )

minima_harness/tools/grep.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import asyncio
+import re
+import shutil
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from minima_harness.agent.tools import AgentTool, ToolResult, error_result
+from minima_harness.ai.types import TextContent
+
+
+class GrepParams(BaseModel):
+    pattern: str
+    path: str = "."
+    include: str | None = None
+
+
+def _re_walk(root: Path, pattern: str, include: str | None) -> str:
+    try:
+        regex = re.compile(pattern)
+    except re.error as exc:
+        return f"(invalid regex: {exc})"
+    glob_pat = include or "*"
+    hits: list[str] = []
+    for file in root.rglob(glob_pat):
+        if not file.is_file():
+            continue
+        try:
+            text = file.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for i, line in enumerate(text.splitlines(), start=1):
+            if regex.search(line):
+                hits.append(f"{file}:{i}:{line}")
+    return "\n".join(hits) if hits else "(no matches)"
+
+
+async def _execute(tool_call_id: str, params, signal, on_update) -> ToolResult:  # noqa: ANN001
+    assert isinstance(params, GrepParams)
+    root = Path(params.path).expanduser()
+    if not root.exists():
+        return error_result(f"grep: no such path: {root}")
+
+    if shutil.which("rg"):
+        cmd = ["rg", "-n", "--color=never"]
+        if params.include:
+            cmd += ["-g", params.include]
+        cmd += ["--", params.pattern, str(root)]
+        proc = await asyncio.create_subprocess_exec(
+            *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+        out, err = await proc.communicate()
+        if proc.returncode not in (0, 1):  # 1 = no matches, 0 = matches
+            return error_result(f"grep: {err.decode('utf-8', 'replace').strip()}")
+        body = out.decode("utf-8", "replace").strip() or "(no matches)"
+    else:
+        body = _re_walk(root, params.pattern, params.include)
+
+    return ToolResult(content=[TextContent(text=body)], details={"path": str(root)})
+
+
+def grep_tool() -> AgentTool:
+    return AgentTool(
+        name="grep",
+        description=(
+            "Search file contents for a regex pattern. Uses ripgrep when available, "
+            "else a pure-Python recursive walk. Returns file:line:match lines."
+        ),
+        parameters=GrepParams,
+        execute=_execute,
+    )

minima_harness/tools/ls.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from minima_harness.agent.tools import AgentTool, ToolResult, error_result
+from minima_harness.ai.types import TextContent
+
+
+class LsParams(BaseModel):
+    path: str = "."
+
+
+async def _execute(tool_call_id: str, params, signal, on_update) -> ToolResult:  # noqa: ANN001
+    assert isinstance(params, LsParams)
+    root = Path(params.path).expanduser()
+    if not root.exists():
+        return error_result(f"ls: no such path: {root}")
+    entries = sorted(root.iterdir(), key=lambda e: (not e.is_dir(), e.name.lower()))
+    if not entries:
+        return ToolResult(content=[TextContent(text="(empty)")])
+    lines = [(f"{e.name}/" if e.is_dir() else e.name) for e in entries]
+    return ToolResult(content=[TextContent(text="\n".join(lines))], details={"count": len(lines)})
+
+
+def ls_tool() -> AgentTool:
+    return AgentTool(
+        name="ls",
+        description=(
+            "List entries in a directory. Directories are suffixed with / and sorted first."
+        ),
+        parameters=LsParams,
+        execute=_execute,
+    )

minima_harness/tools/read.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from minima_harness.agent.tools import AgentTool, ToolResult, error_result
+from minima_harness.ai.types import TextContent
+from minima_harness.tools._io import read_lines
+
+
+class ReadParams(BaseModel):
+    path: str
+    offset: int = Field(default=1, ge=1)
+    limit: int = Field(default=2000, ge=1)
+
+
+async def _execute(tool_call_id: str, params, signal, on_update) -> ToolResult:  # noqa: ANN001
+    assert isinstance(params, ReadParams)
+    p = Path(params.path).expanduser()
+    if not p.exists():
+        return error_result(f"read: no such file: {p}")
+    if p.is_dir():
+        return error_result(f"read: is a directory: {p}")
+    body, n = read_lines(p, offset=params.offset, limit=params.limit)
+    return ToolResult(content=[TextContent(text=body or "(empty)")], details={"lines_read": n})
+
+
+def read_tool() -> AgentTool:
+    return AgentTool(
+        name="read",
+        description=(
+            "Read a text file from the local filesystem. Returns lines with 1-based "
+            "line numbers. Use `offset` and `limit` to page through large files."
+        ),
+        parameters=ReadParams,
+        execute=_execute,
+    )

minima_harness/tools/tasks.py

@@ -0,0 +1,75 @@
+"""The ``tasks`` tool — the agent's live goal checklist (like Claude Code's TodoWrite).
+
+Bound to the session's :class:`~minima_harness.minima.goals.GoalStore` via :func:`tasks_tool`.
+The model calls it to lay out a plan (``set``) and tick items off (``update``) as it works. The
+harness re-injects the list into the system prompt each turn so it stays the "north star".
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+from minima_harness.agent.tools import AgentTool, ToolResult, error_result
+from minima_harness.ai.types import TextContent
+from minima_harness.minima.goals import GoalStore
+
+_MARK = {"completed": "[x]", "in_progress": "[~]", "blocked": "[!]", "pending": "[ ]"}
+
+
+class TaskItem(BaseModel):
+    content: str  # imperative: "Add OAuth login"
+    active_form: str = ""  # present-continuous: "Adding OAuth login"
+    status: str = "pending"  # pending | in_progress | completed | blocked
+
+
+class TasksParams(BaseModel):
+    op: Literal["set", "update", "list"]
+    tasks: list[TaskItem] | None = None  # op=set: replace the whole list
+    task_id: str | None = None  # op=update: which task
+    status: str | None = None  # op=update: new status
+
+
+def _render(store: GoalStore) -> str:
+    goal = store.goal
+    if goal is None or not goal.tasks:
+        return "(no tasks)"
+    done, total = goal.progress()
+    head = f"{done}/{total} done" + (f" · {goal.title}" if goal.title else "")
+    lines = [head] + [f"  {_MARK.get(t.status, '[ ]')} {t.id}  {t.content}" for t in goal.tasks]
+    return "\n".join(lines)
+
+
+def tasks_tool(store: GoalStore) -> AgentTool:
+    async def _execute(tool_call_id: str, params, signal, on_update) -> ToolResult:  # noqa: ANN001
+        assert isinstance(params, TasksParams)
+        if params.op == "set":
+            store.set_tasks([t.model_dump() for t in (params.tasks or [])])
+        elif params.op == "update":
+            if not params.task_id or not params.status:
+                return error_result("tasks update needs task_id and status")
+            if not store.update_task(params.task_id, params.status):
+                return error_result(
+                    f"no task {params.task_id!r} (or bad status); use op=list to see ids"
+                )
+        # op=list falls through to render
+        done, total = store.goal.progress() if store.goal else (0, 0)
+        return ToolResult(
+            content=[TextContent(text=_render(store))],
+            details={"completed": done, "total": total},
+        )
+
+    return AgentTool(
+        name="tasks",
+        description=(
+            "Maintain the goal checklist. Use it for multi-step work (3+ steps); skip it for "
+            "trivial or single-step requests. op='set' replaces the whole list (each task: "
+            "content imperative + optional active_form); op='update' sets one task's status by "
+            "task_id (pending|in_progress|completed|blocked); op='list' shows the current list. "
+            "Keep exactly ONE task in_progress at a time, and mark a task completed ONLY when it "
+            "is actually done and verified — never on intent."
+        ),
+        parameters=TasksParams,
+        execute=_execute,
+    )

minima_harness/tools/write.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from minima_harness.agent.tools import AgentTool, ToolResult
+from minima_harness.ai.types import TextContent
+from minima_harness.tools._io import write_text
+
+
+class WriteParams(BaseModel):
+    path: str
+    content: str
+
+
+async def _execute(tool_call_id: str, params, signal, on_update) -> ToolResult:  # noqa: ANN001
+    assert isinstance(params, WriteParams)
+    p = Path(params.path).expanduser()
+    n = write_text(p, params.content)
+    return ToolResult(
+        content=[TextContent(text=f"wrote {n} lines to {p}")],
+        details={"bytes": len(params.content)},
+    )
+
+
+def write_tool() -> AgentTool:
+    return AgentTool(
+        name="write",
+        description=(
+            "Create or overwrite a file on the local filesystem. Parent directories "
+            "are created automatically. Pass the full intended file contents."
+        ),
+        parameters=WriteParams,
+        execute=_execute,
+    )

minima_harness/tui/__init__.py

@@ -0,0 +1,3 @@
+"""Interactive Textual TUI for the Minima harness (a port of PI's interactive mode)."""
+
+from __future__ import annotations

minima_harness/tui/analytics.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from minima_harness.session import SessionManager, SessionStore
+from minima_harness.session.format import EntryType
+
+
+def cost_position_for(per_model: dict[str, int]) -> float | None:
+    """Mean normalized price-ladder position over used models (0=cheapest..1=priciest).
+
+    The local TUI mirror of the server's routing-optimality ``cost_position``: lower means
+    the agent is routinely landing on cheaper models within the available pool. Returns
+    None when prices can't be resolved (offline / unknown models). Pure + registry-driven.
+    """
+    try:
+        from minima_harness.ai.registry import all_models, find_model_by_id
+    except Exception:  # noqa: BLE001 - registry unavailable
+        return None
+    prices = [m.cost.input + m.cost.output for m in all_models()]
+    if not prices:
+        return None
+    lo, hi = min(prices), max(prices)
+    if hi <= lo:
+        return None
+    weighted = 0.0
+    counted = 0
+    for model_id, count in per_model.items():
+        model = find_model_by_id(model_id)
+        if model is None:
+            continue
+        price = model.cost.input + model.cost.output
+        weighted += ((price - lo) / (hi - lo)) * count
+        counted += count
+    return round(weighted / counted, 4) if counted else None
+
+
+def aggregate_sessions(cwd: Path, n: int = 10) -> dict[str, Any]:
+    """Aggregate stats from the last ``n`` local session files for this project."""
+    mgr = SessionManager()
+    summaries = mgr.list_sessions(cwd)
+    stats: dict[str, Any] = {
+        "sessions": 0,
+        "prompts": 0,
+        "total_in": 0,
+        "total_out": 0,
+        "total_cost": 0.0,
+        "per_model": {},
+    }
+    ape_sum = 0.0  # Σ |actual−est| / actual  (mean absolute percentage error)
+    pred_n = 0  # rows with both an estimate and a realized cost
+    band_n = 0  # rows that carried a predicted cost band
+    band_hits = 0  # rows where the realized cost landed inside the band
+    for s in summaries[:n]:  # list_sessions is sorted most-recent-first → take the front n
+        store = SessionStore.file_backed(s.path)
+        stats["sessions"] += 1
+        for e in store.entries:
+            if e.type == EntryType.USER:
+                stats["prompts"] += 1
+            elif e.type == EntryType.ASSISTANT:
+                p = e.payload
+                stats["total_in"] += p.get("in_tokens", 0)
+                stats["total_out"] += p.get("out_tokens", 0)
+                actual = p.get("cost", 0.0)
+                stats["total_cost"] += actual
+                model = p.get("model", "?")
+                stats["per_model"][model] = stats["per_model"].get(model, 0) + 1
+                # Predictability (guard with .get so pre-Phase-4 rows are simply skipped).
+                est = p.get("est_cost")
+                if est is not None and actual > 0:
+                    ape_sum += abs(actual - est) / max(actual, 1e-9)
+                    pred_n += 1
+                low, high = p.get("est_cost_low"), p.get("est_cost_high")
+                if low is not None and high is not None and actual > 0:
+                    band_n += 1
+                    if low <= actual <= high:
+                        band_hits += 1
+    stats["cost_position"] = cost_position_for(stats["per_model"])
+    stats["pred_n"] = pred_n
+    stats["cost_mape"] = round(ape_sum / pred_n, 4) if pred_n else None
+    stats["band_n"] = band_n
+    stats["band_hit_rate"] = round(band_hits / band_n, 4) if band_n else None
+    return stats
+
+
+def format_stats(stats: dict[str, Any]) -> str:
+    lines = [
+        f"sessions: {stats['sessions']}",
+        f"prompts: {stats['prompts']}",
+        f"tokens: ↑{stats['total_in']} ↓{stats['total_out']}",
+        f"cost: ${stats['total_cost']:.4f}",
+    ]
+    if stats["per_model"]:
+        model_lines = ", ".join(f"{k}×{v}" for k, v in sorted(stats["per_model"].items()))
+        lines.append(f"models: {model_lines}")
+    if stats.get("cost_position") is not None:
+        lines.append(
+            f"cost position: {stats['cost_position']:.2f} (0=cheapest · 1=priciest in pool)"
+        )
+    if stats.get("cost_mape") is not None:
+        lines.append(
+            f"cost predictability: MAPE {stats['cost_mape']:.0%} "
+            f"over {stats['pred_n']} est-vs-actual turn(s)"
+        )
+    if stats.get("band_hit_rate") is not None:
+        lines.append(
+            f"in-range: {stats['band_hit_rate']:.0%} of actuals landed in the predicted "
+            f"band ({stats['band_n']} turn(s))"
+        )
+    return "\n".join(lines)