agentkernel-cli 0.1.0__py3-none-any.whl

agentkernel/tools/builtin/kanban_tool.py

@@ -0,0 +1,100 @@
+"""The `kanban` tool (design §18.3).
+
+Exposes a shared work-queue board to the model so a long mission — or several
+cooperating sub-agents — can file, claim, and complete tasks. The board is the
+durable JSON store in ``kanban.py``; the tool is a thin, single-entry dispatcher
+over it, bound to one board (and an optional worker identity) by the factory.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agentkernel.kanban import render_task
+from agentkernel.tools.base import ToolSpec
+from agentkernel.types import ToolResult
+
+if TYPE_CHECKING:
+    from agentkernel.kanban import Board
+
+
+def _board_view(board: Board) -> str:
+    tasks = board.list()
+    if not tasks:
+        return "(board is empty)"
+    open_n = sum(1 for t in tasks if t.status in ("todo", "in_progress"))
+    lines = [f"Board ({open_n} open / {len(tasks)} total):"]
+    lines += [f"  {render_task(t)}" for t in tasks]
+    return "\n".join(lines)
+
+
+def kanban_tool(board: Board, *, worker: str = "agent") -> ToolSpec:
+    """Build the `kanban` tool over ``board``. ``worker`` labels who claims tasks."""
+
+    def kanban(args: dict) -> ToolResult:
+        action = args["action"]
+
+        if action == "list":
+            return ToolResult("", _board_view(board))
+        if action == "add":
+            title = (args.get("title") or "").strip()
+            if not title:
+                return ToolResult("", "add requires `title`.", is_error=True)
+            task = board.add(title)
+            return ToolResult("", f"Added {task.id}: {task.title}\n\n{_board_view(board)}")
+        if action == "next":
+            task = board.next_todo()
+            if task is None:
+                return ToolResult("", "No unclaimed tasks on the board.")
+            board.claim(task.id, worker)
+            return ToolResult("", f"Claimed {task.id}: {task.title}")
+
+        # The remaining actions target a specific task id.
+        task_id = args.get("id")
+        if not task_id:
+            return ToolResult("", f"{action} requires `id`.", is_error=True)
+        if action == "claim":
+            result = board.claim(task_id, args.get("assignee") or worker)
+        elif action == "complete":
+            result = board.complete(task_id)
+        elif action == "block":
+            result = board.block(task_id, args.get("reason") or "")
+        elif action == "comment":
+            text = (args.get("text") or "").strip()
+            if not text:
+                return ToolResult("", "comment requires `text`.", is_error=True)
+            result = board.comment(task_id, text)
+        else:  # pragma: no cover - schema restricts the enum
+            return ToolResult("", f"unknown action {action!r}", is_error=True)
+
+        if result is None:
+            return ToolResult("", f"No task with id={task_id}.", is_error=True)
+        return ToolResult("", f"{render_task(result)}")
+
+    return ToolSpec(
+        name="kanban",
+        description=(
+            "Coordinate work on a shared task board. Use it to break a large job "
+            "into tasks and track them, or — as a worker — to pull and finish work. "
+            "Actions: list; add (title); next (claim the next todo); claim/complete/"
+            "block/comment (id, plus reason/text where relevant)."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["list", "add", "next", "claim", "complete", "block", "comment"],
+                },
+                "title": {"type": "string", "description": "Task title (for add)."},
+                "id": {"type": "string", "description": "Task id (claim/complete/block/comment)."},
+                "assignee": {"type": "string", "description": "Who claims it (default: you)."},
+                "reason": {"type": "string", "description": "Why it's blocked (for block)."},
+                "text": {"type": "string", "description": "Comment text (for comment)."},
+            },
+            "required": ["action"],
+            "additionalProperties": False,
+        },
+        handler=kanban,
+        category="coordination",
+    )

agentkernel/tools/builtin/search.py

@@ -0,0 +1,225 @@
+"""Read-only discovery tools: find_files, search_text, file_info (design §6.3).
+
+These let the model locate and inspect code without shelling out to `bash`, so
+they work the same on every platform and inside the no-network Docker sandbox.
+Like the file tools, every path is confined to the working directory and every
+failure is returned as an error result, never raised (AGENT.md, design §8.3).
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+
+from agentkernel.context.truncate import truncate_text
+from agentkernel.tools.base import ToolSpec
+from agentkernel.tools.builtin.files import resolve_within
+from agentkernel.types import ToolResult
+
+# Directories that are never worth walking for code search.
+_SKIP_DIRS = {".git", ".venv", "__pycache__", "node_modules", ".agentkernel", ".pytest_cache"}
+
+
+def _is_probably_binary(data: bytes) -> bool:
+    """A cheap heuristic: a NUL byte in the first chunk means "not text"."""
+    return b"\x00" in data[:1024]
+
+
+def _iter_files(base: Path, pattern: str):
+    """Yield files under ``base`` matching ``pattern``, skipping noise dirs."""
+    for p in sorted(base.glob(pattern)):
+        if not p.is_file():
+            continue
+        if any(part in _SKIP_DIRS for part in p.parts):
+            continue
+        yield p
+
+
+def search_tools(working_dir: str = ".", *, max_result_tokens: int = 4096) -> list[ToolSpec]:
+    """Build the read-only discovery toolset bound to ``working_dir``."""
+    root = Path(working_dir).resolve()
+
+    def _rel(p: Path) -> str:
+        return p.relative_to(root).as_posix()
+
+    def find_files(args: dict) -> ToolResult:
+        pattern = args["pattern"]
+        sub = args.get("path", ".")
+        try:
+            base = resolve_within(root, sub)
+        except ValueError as exc:
+            return ToolResult("", str(exc), is_error=True)
+        if not base.is_dir():
+            return ToolResult("", f"Not a directory: {sub!r}", is_error=True)
+        matches = []
+        for p in sorted(base.glob(pattern)):
+            if any(part in _SKIP_DIRS for part in p.relative_to(root).parts):
+                continue
+            matches.append(_rel(p) + ("/" if p.is_dir() else ""))
+        if not matches:
+            return ToolResult("", f"(no files match {pattern!r})")
+        return ToolResult("", truncate_text("\n".join(matches), max_result_tokens))
+
+    def search_text(args: dict) -> ToolResult:
+        pattern = args["pattern"]
+        glob = args.get("glob", "**/*")
+        sub = args.get("path", ".")
+        max_results = int(args.get("max_results", 100))
+        flags = re.IGNORECASE if args.get("ignore_case") else 0
+        try:
+            regex = re.compile(pattern, flags)
+        except re.error as exc:
+            return ToolResult("", f"Invalid regex {pattern!r}: {exc}", is_error=True)
+        try:
+            base = resolve_within(root, sub)
+        except ValueError as exc:
+            return ToolResult("", str(exc), is_error=True)
+        if not base.is_dir():
+            return ToolResult("", f"Not a directory: {sub!r}", is_error=True)
+
+        hits: list[str] = []
+        truncated = False
+        for f in _iter_files(base, glob):
+            try:
+                raw = f.read_bytes()
+            except OSError:
+                continue
+            if _is_probably_binary(raw):
+                continue
+            rel = _rel(f)
+            for lineno, line in enumerate(raw.decode("utf-8", "replace").splitlines(), 1):
+                if regex.search(line):
+                    hits.append(f"{rel}:{lineno}: {line.strip()}")
+                    if len(hits) >= max_results:
+                        truncated = True
+                        break
+            if truncated:
+                break
+        if not hits:
+            return ToolResult("", f"(no matches for {pattern!r})")
+        body = "\n".join(hits)
+        if truncated:
+            body += f"\n... (stopped at {max_results} matches)"
+        return ToolResult("", truncate_text(body, max_result_tokens))
+
+    def file_info(args: dict) -> ToolResult:
+        path = args["path"]
+        try:
+            target = resolve_within(root, path)
+        except ValueError as exc:
+            return ToolResult("", str(exc), is_error=True)
+        if not target.exists():
+            return ToolResult("", f"No such path: {path!r}", is_error=True)
+        st = target.stat()
+        modified = datetime.fromtimestamp(st.st_mtime, tz=UTC).isoformat(timespec="seconds")
+        kind = "directory" if target.is_dir() else "file"
+        lines = [
+            f"path: {_rel(target)}",
+            f"type: {kind}",
+            f"size: {st.st_size} bytes",
+            f"modified: {modified}",
+        ]
+        if target.is_dir():
+            lines.append(f"entries: {sum(1 for _ in target.iterdir())}")
+        elif not _is_probably_binary(target.read_bytes()[:1024]):
+            line_count = target.read_text(encoding="utf-8", errors="replace").count("\n") + 1
+            lines.append(f"lines: {line_count}")
+        else:
+            lines.append("content: binary")
+        return ToolResult("", "\n".join(lines))
+
+    return [
+        ToolSpec(
+            name="find_files",
+            description=(
+                "Find files and directories by glob pattern within the working "
+                "directory — your first move when you know roughly what a file is "
+                "named but not where it lives. Supports `**` for recursive match "
+                "(e.g. '**/*.py', 'src/**/test_*.py'). Returns matching paths; "
+                "noise dirs like .git and __pycache__ are skipped."
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "Glob pattern, e.g. '**/*.py' or 'docs/*.md'.",
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": (
+                            "Subdirectory to search under (default: the working dir root)."
+                        ),
+                    },
+                },
+                "required": ["pattern"],
+                "additionalProperties": False,
+            },
+            handler=find_files,
+            category="search",
+        ),
+        ToolSpec(
+            name="search_text",
+            description=(
+                "Search file contents by regular expression within the working "
+                "directory (a built-in grep) — use it to locate where a symbol, "
+                "string, or pattern is defined or used. Returns 'path:line: text' "
+                "for each match. Filter the files searched with `glob` and narrow "
+                "with `path`; binary files and noise dirs are skipped."
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "pattern": {
+                        "type": "string",
+                        "description": "Python regular expression to match against each line.",
+                    },
+                    "glob": {
+                        "type": "string",
+                        "description": "Restrict to files matching this glob (default '**/*').",
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": (
+                            "Subdirectory to search under (default: the working dir root)."
+                        ),
+                    },
+                    "ignore_case": {
+                        "type": "boolean",
+                        "description": "Case-insensitive match.",
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": "Stop after this many matches (default 100).",
+                    },
+                },
+                "required": ["pattern"],
+                "additionalProperties": False,
+            },
+            handler=search_text,
+            category="search",
+        ),
+        ToolSpec(
+            name="file_info",
+            description=(
+                "Report metadata for a path within the working directory: whether "
+                "it is a file or directory, its size, last-modified time, and line "
+                "count (for text). Cheaper than reading a whole file when you only "
+                "need to know it exists or how big it is."
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "path": {
+                        "type": "string",
+                        "description": "Path relative to the working directory.",
+                    }
+                },
+                "required": ["path"],
+                "additionalProperties": False,
+            },
+            handler=file_info,
+            category="search",
+        ),
+    ]

agentkernel/tools/builtin/shell.py

@@ -0,0 +1,67 @@
+"""The bash tool (design §6.3, §10.3).
+
+Flagged ``runs_code`` + ``mutates`` + ``requires_approval``, so the loop gates
+it through the approver and it executes only inside the injected ``Sandbox``,
+confined to the working directory. Output is assembled here; the loop applies
+the shared §8.4 truncation before it enters context.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agentkernel.tools.base import ToolSpec
+from agentkernel.types import ToolResult
+
+if TYPE_CHECKING:
+    from agentkernel.approval import Sandbox
+
+_BASH_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "command": {
+            "type": "string",
+            "description": "The shell command to run in the working directory.",
+        }
+    },
+    "required": ["command"],
+    "additionalProperties": False,
+}
+
+
+def bash_tool(sandbox: Sandbox, working_dir: str = ".", *, timeout: int = 60) -> ToolSpec:
+    """Build the bash tool bound to ``sandbox`` and ``working_dir``."""
+
+    def bash(args: dict) -> ToolResult:
+        command = args["command"]
+        exit_code, stdout, stderr = sandbox.run(
+            command, cwd=working_dir, timeout=timeout
+        )
+        sections = []
+        if stdout:
+            sections.append(stdout.rstrip("\n"))
+        if stderr:
+            sections.append(f"[stderr]\n{stderr.rstrip(chr(10))}")
+        if exit_code != 0:
+            sections.append(f"[exit code {exit_code}]")
+        content = "\n".join(sections) if sections else "(no output)"
+        return ToolResult(
+            "",
+            content,
+            is_error=exit_code != 0,
+            data={"exit_code": exit_code},
+        )
+
+    return ToolSpec(
+        name="bash",
+        description=(
+            "Run a shell command in the working directory and return its output. "
+            "Use for builds, tests, git, and filesystem operations."
+        ),
+        parameters=_BASH_SCHEMA,
+        handler=bash,
+        requires_approval=True,
+        mutates=True,
+        runs_code=True,
+        category="shell",
+    )

agentkernel/tools/builtin/todo.py

@@ -0,0 +1,106 @@
+"""In-session todo tool (design §18.4).
+
+A lightweight task list the model maintains while working through a multi-step
+job, so its plan stays legible to both the model and the user. State is held in
+memory for the life of one runtime (a session), bound into the handler by the
+factory — no global state, no persistence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from agentkernel.tools.base import ToolSpec
+from agentkernel.types import ToolResult
+
+_STATUS_MARK = {"pending": "[ ]", "in_progress": "[~]", "done": "[x]"}
+
+
+@dataclass
+class TodoItem:
+    id: int
+    text: str
+    status: str = "pending"  # pending | in_progress | done
+
+
+@dataclass
+class TodoList:
+    """The session's task list. Bound into the todo tool's handler."""
+
+    _items: list[TodoItem] = field(default_factory=list)
+    _next_id: int = 1
+
+    def add(self, text: str) -> TodoItem:
+        item = TodoItem(self._next_id, text.strip())
+        self._items.append(item)
+        self._next_id += 1
+        return item
+
+    def set_status(self, item_id: int, status: str) -> TodoItem | None:
+        for item in self._items:
+            if item.id == item_id:
+                item.status = status
+                return item
+        return None
+
+    def clear(self) -> None:
+        self._items.clear()
+
+    def render(self) -> str:
+        if not self._items:
+            return "(todo list is empty)"
+        done = sum(1 for i in self._items if i.status == "done")
+        lines = [f"Todos ({done}/{len(self._items)} done):"]
+        lines += [f"  {_STATUS_MARK[i.status]} {i.id}. {i.text}" for i in self._items]
+        return "\n".join(lines)
+
+
+def todo_tool(todo_list: TodoList) -> ToolSpec:
+    """Build the `todo` tool over a session task list."""
+
+    def todo(args: dict) -> ToolResult:
+        action = args["action"]
+        if action == "add":
+            text = (args.get("text") or "").strip()
+            if not text:
+                return ToolResult("", "add requires non-empty `text`.", is_error=True)
+            todo_list.add(text)
+            return ToolResult("", todo_list.render())
+        if action in ("start", "complete"):
+            if "id" not in args:
+                return ToolResult("", f"{action} requires `id`.", is_error=True)
+            status = "in_progress" if action == "start" else "done"
+            if todo_list.set_status(int(args["id"]), status) is None:
+                return ToolResult("", f"No todo with id={args['id']}.", is_error=True)
+            return ToolResult("", todo_list.render())
+        if action == "clear":
+            todo_list.clear()
+            return ToolResult("", "Cleared the todo list.")
+        # action == "list"
+        return ToolResult("", todo_list.render())
+
+    return ToolSpec(
+        name="todo",
+        description=(
+            "Maintain a short task list for the current job so your plan stays "
+            "visible. Use it for multi-step work: add the steps, mark one `start` "
+            "as you begin it and `complete` when done, and `list` to review. "
+            "Actions: add (needs text), start/complete (need id), list, clear."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["add", "start", "complete", "list", "clear"],
+                    "description": "The operation to perform.",
+                },
+                "text": {"type": "string", "description": "Task text (for add)."},
+                "id": {"type": "integer", "description": "Task id (for start/complete)."},
+            },
+            "required": ["action"],
+            "additionalProperties": False,
+        },
+        handler=todo,
+        category="planning",
+    )

agentkernel/tui/__init__.py

@@ -0,0 +1,50 @@
+"""Terminal UI for agentkernel — a curses-based interactive chat interface.
+
+Provides a split-pane terminal UI with:
+- Scrollable chat history (color-coded by role)
+- Multi-line input area
+- Status bar (model, tokens, cost)
+- Background agent execution with live status indicator
+
+Usage:
+    from agentkernel.tui import run_tui
+    run_tui(config)  # or: uv run agentkernel tui
+
+On Windows, ``pip install windows-curses`` first.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentkernel.config import Config
+
+
+def run_tui(config: Config) -> int:
+    """Entry point: initialise curses and run the TUI event loop.
+
+    Returns 0 on clean exit, 1 on error.
+    """
+    try:
+        import curses
+    except ImportError:
+        print(
+            "The TUI requires the `curses` module, which is not available.\n"
+            "On Windows, install it with:  pip install windows-curses\n"
+            "On Unix, it should be included with your Python installation.",
+            file=sys.stderr,
+        )
+        return 1
+
+    from agentkernel.tui.app import TuiApp
+
+    try:
+        app = TuiApp(config)
+        return curses.wrapper(app.run)
+    except KeyboardInterrupt:
+        return 0
+    except Exception as exc:
+        print(f"TUI error: {exc}", file=sys.stderr)
+        return 1