koina 0.1.0__tar.gz

koina-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoffrey Guéret
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

koina-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: koina
+Version: 0.1.0
+Summary: An agentic toolset: provider-neutral tools and dispatch for building agents on low-level LLM SDKs
+Keywords: agents,agentic,llm,tool-use,function-calling,ai
+Author: Geoffrey Guéret
+Author-email: Geoffrey Guéret <geoffrey@gueret.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/ggueret/koina
+Project-URL: Repository, https://github.com/ggueret/koina.git
+Project-URL: Documentation, https://github.com/ggueret/koina#readme
+Project-URL: Issues, https://github.com/ggueret/koina/issues
+Project-URL: Changelog, https://github.com/ggueret/koina/releases
+Description-Content-Type: text/markdown
+
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/wordmark-dark.svg">
+    <img src="assets/brand/wordmark.svg" alt="koina" width="240">
+  </picture>
+</h1>
+
+<p align="center"><em>An agentic toolset.</em></p>
+
+<p align="center">
+  Reusable, provider-neutral building blocks for agents on low-level LLM SDKs:
+  the six core file/shell tools (Read, Write, Edit, Bash, Glob, Grep), a
+  never-raising <code>dispatch</code>, structured JSONL logging, and a thin
+  adapter per provider. koina gives you the tools and the dispatch; the agentic
+  loop stays in your code.
+</p>
+
+## Requirements
+
+- Python 3.12+
+- ripgrep (`rg`) on PATH (for Glob and Grep)
+
+## Install
+
+```bash
+uv add koina
+```
+
+The library depends only on `pydantic`. Provider SDKs (`anthropic`, `openai`)
+are the caller's dependency, used in your loop, not by koina.
+
+## Usage
+
+`dispatch` and the tools are provider-neutral; an adapter translates a provider's
+wire format to and from the neutral `ToolCall`/`ToolResult`. With the Anthropic
+adapter:
+
+```python
+from pathlib import Path
+from anthropic import AsyncAnthropic
+from koina import default_registry, dispatch, ToolContext
+from koina.adapters import anthropic as adapter
+
+client = AsyncAnthropic()
+reg = default_registry()
+ctx = ToolContext(cwd=Path.cwd())
+msgs = [{"role": "user", "content": "List the Python files."}]
+
+while True:
+    resp = await client.messages.create(
+        model="claude-opus-4-8", max_tokens=4096,
+        messages=msgs, tools=adapter.tools_param(reg),
+    )
+    msgs.append({"role": "assistant", "content": resp.content})
+    calls = adapter.parse_tool_calls(resp.content)
+    if not calls:
+        break
+    results = [await dispatch(c, reg, ctx) for c in calls]
+    msgs.append(adapter.format_results(results))
+```
+
+Swap `koina.adapters.anthropic` for `koina.adapters.openai` to run the same tools
+against the OpenAI Chat Completions API (or any OpenAI-compatible server, e.g.
+llama.cpp). See `examples/` for runnable read-only code-review scripts on both.
+
+## What's in the box
+
+- **Six core tools** (Read, Write, Edit, Bash, Glob, Grep), faithful to Claude
+  Code's observable behavior, headless (no permissions or hooks).
+- **`dispatch` never raises**: it always returns a `ToolResult` (errors set
+  `is_error=True`).
+- **Provider-neutral core** (`ToolCall`, `ToolResult`) with per-provider adapters
+  (`koina.adapters.anthropic`, `koina.adapters.openai`). The library never imports
+  a provider SDK at runtime.
+- **Structured logging**: typed events (tool calls, model calls, token usage,
+  reasoning) emitted to a pluggable `EventSink` (`JsonlSink`/`NullSink`), so a run
+  reconstructs from a JSONL transcript. Off by default, near-zero overhead when
+  inactive.
+
+Permissions, web tools, and concurrency orchestration are out of scope.

koina-0.1.0/README.md

@@ -0,0 +1,80 @@
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/brand/wordmark-dark.svg">
+    <img src="assets/brand/wordmark.svg" alt="koina" width="240">
+  </picture>
+</h1>
+
+<p align="center"><em>An agentic toolset.</em></p>
+
+<p align="center">
+  Reusable, provider-neutral building blocks for agents on low-level LLM SDKs:
+  the six core file/shell tools (Read, Write, Edit, Bash, Glob, Grep), a
+  never-raising <code>dispatch</code>, structured JSONL logging, and a thin
+  adapter per provider. koina gives you the tools and the dispatch; the agentic
+  loop stays in your code.
+</p>
+
+## Requirements
+
+- Python 3.12+
+- ripgrep (`rg`) on PATH (for Glob and Grep)
+
+## Install
+
+```bash
+uv add koina
+```
+
+The library depends only on `pydantic`. Provider SDKs (`anthropic`, `openai`)
+are the caller's dependency, used in your loop, not by koina.
+
+## Usage
+
+`dispatch` and the tools are provider-neutral; an adapter translates a provider's
+wire format to and from the neutral `ToolCall`/`ToolResult`. With the Anthropic
+adapter:
+
+```python
+from pathlib import Path
+from anthropic import AsyncAnthropic
+from koina import default_registry, dispatch, ToolContext
+from koina.adapters import anthropic as adapter
+
+client = AsyncAnthropic()
+reg = default_registry()
+ctx = ToolContext(cwd=Path.cwd())
+msgs = [{"role": "user", "content": "List the Python files."}]
+
+while True:
+    resp = await client.messages.create(
+        model="claude-opus-4-8", max_tokens=4096,
+        messages=msgs, tools=adapter.tools_param(reg),
+    )
+    msgs.append({"role": "assistant", "content": resp.content})
+    calls = adapter.parse_tool_calls(resp.content)
+    if not calls:
+        break
+    results = [await dispatch(c, reg, ctx) for c in calls]
+    msgs.append(adapter.format_results(results))
+```
+
+Swap `koina.adapters.anthropic` for `koina.adapters.openai` to run the same tools
+against the OpenAI Chat Completions API (or any OpenAI-compatible server, e.g.
+llama.cpp). See `examples/` for runnable read-only code-review scripts on both.
+
+## What's in the box
+
+- **Six core tools** (Read, Write, Edit, Bash, Glob, Grep), faithful to Claude
+  Code's observable behavior, headless (no permissions or hooks).
+- **`dispatch` never raises**: it always returns a `ToolResult` (errors set
+  `is_error=True`).
+- **Provider-neutral core** (`ToolCall`, `ToolResult`) with per-provider adapters
+  (`koina.adapters.anthropic`, `koina.adapters.openai`). The library never imports
+  a provider SDK at runtime.
+- **Structured logging**: typed events (tool calls, model calls, token usage,
+  reasoning) emitted to a pluggable `EventSink` (`JsonlSink`/`NullSink`), so a run
+  reconstructs from a JSONL transcript. Off by default, near-zero overhead when
+  inactive.
+
+Permissions, web tools, and concurrency orchestration are out of scope.

koina-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "koina"
+version = "0.1.0"
+description = "An agentic toolset: provider-neutral tools and dispatch for building agents on low-level LLM SDKs"
+readme = "README.md"
+authors = [
+    { name = "Geoffrey Guéret", email = "geoffrey@gueret.dev" }
+]
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["agents", "agentic", "llm", "tool-use", "function-calling", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2",
+]
+
+[project.urls]
+Homepage = "https://github.com/ggueret/koina"
+Repository = "https://github.com/ggueret/koina.git"
+Documentation = "https://github.com/ggueret/koina#readme"
+Issues = "https://github.com/ggueret/koina/issues"
+Changelog = "https://github.com/ggueret/koina/releases"
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+examples = [
+    "anthropic>=0.105.2",
+    "openai>=1.0",
+]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.15",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+cache_dir = ".cache/pytest"
+addopts = "--cov --cov-report=term-missing"
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+cache-dir = ".cache/ruff"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "RUF"]
+ignore = ["E501"]  # line length is enforced by the formatter
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+cache_dir = ".cache/mypy"
+
+[tool.coverage.run]
+source = ["src/koina"]
+branch = true
+data_file = ".cache/coverage/.coverage"
+
+[tool.coverage.report]
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[tool.coverage.html]
+directory = ".cache/coverage/html"

koina-0.1.0/src/koina/__init__.py

@@ -0,0 +1,36 @@
+from .calls import ToolCall, ToolResult
+from .context import ReadLimits, ToolContext
+from .observability import (
+    Event,
+    EventSink,
+    JsonlSink,
+    ModelResponse,
+    NullSink,
+    Thinking,
+    ToolEnd,
+    ToolStart,
+    Usage,
+)
+from .registry import ToolRegistry, default_registry, dispatch
+from .tool import Tool, ToolError
+
+__all__ = [
+    "Event",
+    "EventSink",
+    "JsonlSink",
+    "ModelResponse",
+    "NullSink",
+    "ReadLimits",
+    "Thinking",
+    "Tool",
+    "ToolCall",
+    "ToolContext",
+    "ToolEnd",
+    "ToolError",
+    "ToolRegistry",
+    "ToolResult",
+    "ToolStart",
+    "Usage",
+    "default_registry",
+    "dispatch",
+]

koina-0.1.0/src/koina/_ripgrep.py

@@ -0,0 +1,19 @@
+import asyncio
+
+
+async def run_rg(args: list[str], cwd: str) -> tuple[int, str]:
+    """Run ripgrep, returning (returncode, stdout). rg exits 1 when no matches."""
+    proc = await asyncio.create_subprocess_exec(
+        "rg",
+        *args,
+        cwd=cwd,
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, stderr = await proc.communicate()
+    if proc.returncode not in (0, 1):
+        raise RuntimeError(
+            stderr.decode("utf-8", errors="replace").strip() or "rg failed"
+        )
+    return proc.returncode or 0, stdout.decode("utf-8", errors="replace")

koina-0.1.0/src/koina/adapters/anthropic.py

@@ -0,0 +1,103 @@
+"""Anthropic Messages API adapter.
+
+Maps koina's neutral tool types to and from Anthropic wire shapes: `tools_param`
+(schema export), `parse_tool_calls` (tool_use blocks -> `ToolCall`),
+`format_results` (`ToolResult` -> tool_result block, wrapping errors in
+`<tool_use_error>`), plus `usage_event` / `thinking_events`.
+"""
+
+from typing import Any
+
+from ..calls import ToolCall, ToolResult
+from ..observability import Thinking, Usage
+from ..registry import ToolRegistry
+
+
+def tools_param(registry: ToolRegistry) -> list[dict[str, object]]:
+    return [
+        {
+            "name": tool.name,
+            "description": tool.description,
+            "input_schema": tool.input_json_schema(),
+        }
+        for tool in registry.tools()
+    ]
+
+
+def parse_tool_calls(content: Any) -> list[ToolCall]:
+    calls: list[ToolCall] = []
+    for block in content:
+        if getattr(block, "type", None) == "tool_use":
+            calls.append(
+                ToolCall(id=block.id, name=block.name, input=dict(block.input))
+            )
+    return calls
+
+
+def format_results(results: list[ToolResult]) -> dict[str, object]:
+    blocks: list[dict[str, object]] = []
+    for r in results:
+        # Claude Code wraps tool errors in this marker; it is Anthropic-specific,
+        # so it is applied here, not baked into the neutral ToolResult.content.
+        content = (
+            f"<tool_use_error>{r.content}</tool_use_error>" if r.is_error else r.content
+        )
+        block: dict[str, object] = {
+            "type": "tool_result",
+            "tool_use_id": r.id,
+            "content": content,
+        }
+        if r.is_error:
+            block["is_error"] = True
+        blocks.append(block)
+    return {"role": "user", "content": blocks}
+
+
+def usage_event(
+    resp: Any, *, turn: int | None = None, parent_id: str | None = None
+) -> Usage:
+    u = resp.usage
+    cache_read = getattr(u, "cache_read_input_tokens", 0) or 0
+    cache_creation = getattr(u, "cache_creation_input_tokens", 0) or 0
+    extra: dict[str, int] = {}
+    if cache_creation:
+        # Anthropic-only counter (cache-write premium); kept out of the neutral
+        # fields so the schema does not bias toward one provider.
+        extra["cache_creation_input_tokens"] = cache_creation
+    return Usage(
+        response_id=getattr(resp, "id", None),
+        input_tokens=u.input_tokens,
+        output_tokens=u.output_tokens,
+        cached_input_tokens=cache_read,
+        reasoning_tokens=0,  # Anthropic folds thinking into output_tokens
+        extra=extra,
+        turn=turn,
+        parent_id=parent_id,
+    )
+
+
+def thinking_events(
+    content: Any, *, turn: int | None = None, parent_id: str | None = None
+) -> list[Thinking]:
+    events: list[Thinking] = []
+    for block in content:
+        btype = getattr(block, "type", None)
+        if btype == "thinking":
+            signature = getattr(block, "signature", None)
+            extra: dict[str, object] = {}
+            if signature is not None:
+                # Anthropic-only thinking-block signature; out of the neutral core.
+                extra["signature"] = signature
+            events.append(
+                Thinking(
+                    thinking=getattr(block, "thinking", ""),
+                    extra=extra,
+                    turn=turn,
+                    parent_id=parent_id,
+                )
+            )
+        elif btype == "redacted_thinking":
+            events.append(
+                Thinking(thinking="", redacted=True, turn=turn, parent_id=parent_id)
+            )
+    return events

koina-0.1.0/src/koina/adapters/openai.py

@@ -0,0 +1,76 @@
+"""OpenAI Chat Completions adapter (and OpenAI-compatible servers).
+
+Maps koina's neutral tool types to and from OpenAI wire shapes: `tools_param`
+(schema export as function tools), `parse_tool_calls` (tool_calls -> `ToolCall`,
+tolerant of malformed JSON arguments), `format_results` (`ToolResult` -> tool
+message), plus `usage_event` / `thinking_events`.
+"""
+
+import json
+from typing import Any
+
+from ..calls import ToolCall, ToolResult
+from ..observability import Thinking, Usage
+from ..registry import ToolRegistry
+
+
+def tools_param(registry: ToolRegistry) -> list[dict[str, object]]:
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": tool.name,
+                "description": tool.description,
+                "parameters": tool.input_json_schema(),
+            },
+        }
+        for tool in registry.tools()
+    ]
+
+
+def parse_tool_calls(message: Any) -> list[ToolCall]:
+    calls: list[ToolCall] = []
+    for tc in getattr(message, "tool_calls", None) or []:
+        fn = tc.function
+        try:
+            args = json.loads(fn.arguments or "{}")
+        except (ValueError, TypeError):
+            args = {}
+        if not isinstance(args, dict):
+            args = {}
+        calls.append(ToolCall(id=tc.id, name=fn.name, input=args))
+    return calls
+
+
+def format_results(results: list[ToolResult]) -> list[dict[str, object]]:
+    return [
+        {"role": "tool", "tool_call_id": r.id, "content": r.content} for r in results
+    ]
+
+
+def usage_event(
+    resp: Any, *, turn: int | None = None, parent_id: str | None = None
+) -> Usage:
+    u = resp.usage
+    prompt_details = getattr(u, "prompt_tokens_details", None)
+    completion_details = getattr(u, "completion_tokens_details", None)
+    cached = getattr(prompt_details, "cached_tokens", 0) or 0
+    reasoning = getattr(completion_details, "reasoning_tokens", 0) or 0
+    return Usage(
+        response_id=getattr(resp, "id", None),
+        input_tokens=u.prompt_tokens,
+        output_tokens=u.completion_tokens,
+        cached_input_tokens=cached,
+        reasoning_tokens=reasoning,
+        turn=turn,
+        parent_id=parent_id,
+    )
+
+
+def thinking_events(
+    message: Any, *, turn: int | None = None, parent_id: str | None = None
+) -> list[Thinking]:
+    reasoning = getattr(message, "reasoning_content", None)
+    if not reasoning:
+        return []
+    return [Thinking(thinking=reasoning, turn=turn, parent_id=parent_id)]

koina-0.1.0/src/koina/calls.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class ToolCall:
+    """A request to run a tool, decoded from a provider response.
+
+    `input` is the raw argument mapping; `dispatch` validates it against the
+    tool's `Input` model.
+    """
+
+    id: str
+    name: str
+    input: dict[str, object]
+
+
+@dataclass
+class ToolResult:
+    """The outcome of a tool call, ready to be formatted back for a provider.
+
+    `content` is the rendered, provider-neutral text; `is_error` marks a failure
+    (an adapter may decorate error content for its provider).
+    """
+
+    id: str
+    # name is carried for adapters that format results by function name
+    # (e.g. Gemini's functionResponse); the Anthropic adapter matches by id only.
+    name: str
+    content: str
+    is_error: bool = False

koina-0.1.0/src/koina/context.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .observability import EventSink, NullSink
+
+
+@dataclass
+class ReadLimits:
+    """Caps applied by `Read`: it keeps at most
+    ``min(max_bytes, max_tokens * 4)`` bytes of a file."""
+
+    max_tokens: int = 25_000
+    max_bytes: int = 256 * 1024
+
+
+@dataclass
+class ToolContext:
+    """State shared across tool calls, passed to every `run()`.
+
+    Attributes:
+        cwd: Working directory used to resolve relative paths. `Bash` updates it,
+            so a ``cd`` persists across calls.
+        read_limits: Byte/token caps applied by `Read`.
+        events: Observability sink; defaults to `NullSink` (no-op).
+    """
+
+    cwd: Path
+    read_limits: ReadLimits = field(default_factory=ReadLimits)
+    events: EventSink = field(default_factory=NullSink)

koina-0.1.0/src/koina/observability.py

@@ -0,0 +1,90 @@
+import time
+import uuid
+from pathlib import Path
+from typing import Annotated, Literal, Protocol
+
+from pydantic import BaseModel, Field
+
+
+class _Event(BaseModel):
+    id: str = Field(default_factory=lambda: uuid.uuid4().hex)
+    ts: float = Field(default_factory=time.time)
+    turn: int | None = None
+    parent_id: str | None = None
+
+
+class ToolStart(_Event):
+    type: Literal["tool_start"] = "tool_start"
+    tool: str
+    tool_call_id: str
+    input: dict[str, object]
+
+
+class ToolEnd(_Event):
+    type: Literal["tool_end"] = "tool_end"
+    tool: str
+    tool_call_id: str
+    duration_ms: float
+    is_error: bool
+    output_bytes: int
+
+
+class ModelResponse(_Event):
+    type: Literal["model_response"] = "model_response"
+    response_id: str
+    model: str
+    stop_reason: str | None = None
+    tool_call_ids: list[str] = Field(default_factory=list)
+
+
+class Thinking(_Event):
+    type: Literal["thinking"] = "thinking"
+    thinking: str
+    redacted: bool = False
+    extra: dict[str, object] = Field(default_factory=dict)  # provider-specific
+
+
+class Usage(_Event):
+    type: Literal["usage"] = "usage"
+    response_id: str | None = None
+    input_tokens: int
+    output_tokens: int
+    cached_input_tokens: int = 0  # cache read, present in every provider
+    reasoning_tokens: int = 0  # OpenAI/Gemini; 0 on Anthropic (folded in output)
+    extra: dict[str, int] = Field(default_factory=dict)  # provider-specific
+
+
+Event = Annotated[
+    ToolStart | ToolEnd | ModelResponse | Thinking | Usage,
+    Field(discriminator="type"),
+]
+
+
+class EventSink(Protocol):
+    def emit(self, event: Event) -> None: ...
+
+
+class NullSink:
+    def emit(self, event: Event) -> None:
+        return None
+
+
+class JsonlSink:
+    def __init__(self, path: str | Path) -> None:
+        # buffering=1 -> line-buffered: each emit flushes one terminated line.
+        self._fh = open(path, "a", encoding="utf-8", buffering=1)
+
+    def emit(self, event: Event) -> None:
+        try:
+            self._fh.write(event.model_dump_json() + "\n")
+        except Exception:
+            pass  # emit must never raise; logging is best-effort
+
+    def close(self) -> None:
+        self._fh.close()
+
+    def __enter__(self) -> "JsonlSink":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

koina-0.1.0/src/koina/registry.py

@@ -0,0 +1,103 @@
+import time
+from typing import Any
+
+from pydantic import ValidationError
+
+from .calls import ToolCall, ToolResult
+from .context import ToolContext
+from .observability import Event, ToolEnd, ToolStart
+from .tool import Tool, ToolError
+
+
+class ToolRegistry:
+    def __init__(
+        self, tools: tuple[Tool[Any, Any], ...] | list[Tool[Any, Any]] = ()
+    ) -> None:
+        self._by_name: dict[str, Tool[Any, Any]] = {}
+        for tool in tools:
+            self.register(tool)
+
+    def register(self, tool: Tool[Any, Any]) -> None:
+        self._by_name[tool.name] = tool
+        for alias in tool.aliases:
+            self._by_name[alias] = tool
+
+    def get(self, name: str) -> Tool[Any, Any] | None:
+        return self._by_name.get(name)
+
+    def tools(self) -> list[Tool[Any, Any]]:
+        unique: dict[str, Tool[Any, Any]] = {}
+        for tool in self._by_name.values():
+            unique[tool.name] = tool
+        return list(unique.values())
+
+
+def _error(call: ToolCall, message: str) -> ToolResult:
+    return ToolResult(id=call.id, name=call.name, content=message, is_error=True)
+
+
+async def _execute(
+    call: ToolCall, registry: ToolRegistry, ctx: ToolContext
+) -> ToolResult:
+    tool = registry.get(call.name)
+    if tool is None:
+        return _error(call, f"No such tool available: {call.name}")
+    try:
+        parsed = tool.Input.model_validate(call.input)
+    except ValidationError as exc:
+        return _error(call, f"InputValidationError: {exc}")
+    try:
+        output = await tool.run(parsed, ctx)
+        return ToolResult(
+            id=call.id, name=call.name, content=tool.render_result(output)
+        )
+    except ToolError as exc:
+        return _error(call, str(exc))
+    except Exception as exc:  # dispatch must never raise
+        return _error(call, f"{type(exc).__name__}: {exc}")
+
+
+def _safe_emit(ctx: ToolContext, event: Event) -> None:
+    try:
+        ctx.events.emit(event)
+    except Exception:  # logging is best-effort; never break dispatch
+        pass
+
+
+async def dispatch(
+    call: ToolCall, registry: ToolRegistry, ctx: ToolContext
+) -> ToolResult:
+    """Run a tool call and return its result.
+
+    Never raises: an unknown tool, an input that fails validation, a `ToolError`,
+    or any unexpected exception from the tool is converted into a
+    `ToolResult(is_error=True)`. A `ToolStart`/`ToolEnd` pair is emitted to
+    `ctx.events` around execution.
+    """
+    start = ToolStart(tool=call.name, tool_call_id=call.id, input=call.input)
+    _safe_emit(ctx, start)
+    t0 = time.monotonic()
+    result = await _execute(call, registry, ctx)
+    _safe_emit(
+        ctx,
+        ToolEnd(
+            tool=call.name,
+            tool_call_id=call.id,
+            duration_ms=(time.monotonic() - t0) * 1000,
+            is_error=result.is_error,
+            output_bytes=len(result.content.encode("utf-8")),
+            parent_id=start.id,
+        ),
+    )
+    return result
+
+
+def default_registry() -> ToolRegistry:
+    from .tools.bash import Bash
+    from .tools.edit import Edit
+    from .tools.glob import Glob
+    from .tools.grep import Grep
+    from .tools.read import Read
+    from .tools.write import Write
+
+    return ToolRegistry([Read(), Write(), Edit(), Bash(), Glob(), Grep()])

koina-0.1.0/src/koina/tool.py

@@ -0,0 +1,39 @@
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+from .context import ToolContext
+
+
+class ToolError(Exception):
+    """Raise inside `run()` to signal a user-facing tool failure.
+
+    `dispatch` catches it and returns a `ToolResult(is_error=True)`; it never
+    propagates out of `dispatch`.
+    """
+
+
+class Tool[I: BaseModel, O](ABC):
+    """Base class for a tool.
+
+    Parameterize it with the pydantic input model and the output type, e.g.
+    ``class Read(Tool[ReadInput, ReadOutput])``, so that `run` and
+    `render_result` are type-checked against each other. `name`, `description`
+    and `Input` are required class attributes; `aliases` is optional.
+    """
+
+    name: ClassVar[str]
+    aliases: ClassVar[tuple[str, ...]] = ()
+    description: ClassVar[str]
+    Input: ClassVar[type[BaseModel]]
+
+    @abstractmethod
+    async def run(self, input: I, ctx: ToolContext) -> O: ...
+
+    @abstractmethod
+    def render_result(self, output: O) -> str: ...
+
+    @classmethod
+    def input_json_schema(cls) -> dict[str, object]:
+        return cls.Input.model_json_schema()

koina-0.1.0/src/koina/tools/bash.py

@@ -0,0 +1,160 @@
+import asyncio
+import os
+import signal
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..context import ToolContext
+from ..tool import Tool
+
+DEFAULT_TIMEOUT_MS = 120_000
+MAX_TIMEOUT_MS = 600_000
+MAX_OUTPUT_CHARS = 30_000
+_MARKER = "__KOINA_CWD__:"
+_READ_CHUNK = 65_536
+# Bytes kept from the end of stdout so the trailing CWD marker survives truncation.
+_TAIL_BYTES = 8_192
+
+
+async def _drain_capped(
+    stream: asyncio.StreamReader, cap: int, keep_tail: bool
+) -> tuple[bytes, bytes, bool]:
+    """Read a stream to EOF while bounding memory.
+
+    Keeps at most ``cap`` bytes from the head and, when ``keep_tail``, the last
+    ``_TAIL_BYTES`` bytes. Returns ``(head, tail, overflowed)``. Peak memory is
+    ``cap + _TAIL_BYTES`` regardless of how much the command emits.
+    """
+    head = bytearray()
+    tail = bytearray()
+    overflowed = False
+    while True:
+        chunk = await stream.read(_READ_CHUNK)
+        if not chunk:
+            break
+        room = cap - len(head)
+        if room > 0:
+            head += chunk[:room]
+        if len(chunk) > room:
+            overflowed = True
+        if keep_tail:
+            tail += chunk
+            if len(tail) > _TAIL_BYTES:
+                del tail[: len(tail) - _TAIL_BYTES]
+    return bytes(head), bytes(tail), overflowed
+
+
+def _strip_marker_prefix(text: str) -> str:
+    """Drop a partial ``_MARKER`` prefix left at the end of a truncated head."""
+    for k in range(min(len(_MARKER), len(text)), 0, -1):
+        if text.endswith(_MARKER[:k]):
+            return text[:-k]
+    return text
+
+
+class BashInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    command: str = Field(description="The command to execute")
+    timeout: int | None = Field(
+        default=None, description="Optional timeout in milliseconds"
+    )
+    description: str | None = Field(
+        default=None, description="Advisory description, no effect"
+    )
+
+
+@dataclass
+class BashOutput:
+    stdout: str
+    stderr: str
+    exit_code: int
+    timed_out: bool
+    truncated: bool
+
+
+class Bash(Tool[BashInput, BashOutput]):
+    name = "Bash"
+    description = (
+        "Execute a bash command. The working directory persists between calls."
+    )
+    Input = BashInput
+
+    async def run(self, input: BashInput, ctx: ToolContext) -> BashOutput:
+        timeout_ms = min(input.timeout or DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS)
+        script = (
+            f"{input.command}\n__rc=$?\nprintf '\\n{_MARKER}%s' \"$PWD\"\nexit $__rc"
+        )
+        proc = await asyncio.create_subprocess_exec(
+            "bash",
+            "-c",
+            script,
+            cwd=str(ctx.cwd),
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            start_new_session=True,
+        )
+        assert proc.stdout is not None and proc.stderr is not None
+        try:
+            (
+                (out_head, out_tail, out_over),
+                (err_head, _, err_over),
+            ) = await asyncio.wait_for(
+                asyncio.gather(
+                    _drain_capped(proc.stdout, MAX_OUTPUT_CHARS, keep_tail=True),
+                    _drain_capped(proc.stderr, MAX_OUTPUT_CHARS, keep_tail=False),
+                ),
+                timeout=timeout_ms / 1000,
+            )
+            await proc.wait()
+        except TimeoutError:
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                proc.kill()
+            await proc.wait()
+            return BashOutput(
+                stdout="", stderr="", exit_code=124, timed_out=True, truncated=False
+            )
+
+        # The CWD marker is printed last. If stdout overflowed the cap it lives in
+        # the tail; otherwise the whole output (marker included) is in the head.
+        marker_blob = (out_tail if out_over else out_head).decode(
+            "utf-8", errors="replace"
+        )
+        marker_index = marker_blob.rfind(_MARKER)
+        if marker_index != -1:
+            new_cwd = marker_blob[marker_index + len(_MARKER) :].strip()
+            if new_cwd:
+                ctx.cwd = Path(new_cwd)
+
+        stdout = out_head.decode("utf-8", errors="replace")
+        if out_over:
+            stdout = _strip_marker_prefix(stdout).rstrip("\n") + "\n(output truncated)"
+        elif marker_index != -1:
+            stdout = stdout[: stdout.rfind(_MARKER)].rstrip("\n")
+
+        stderr = err_head.decode("utf-8", errors="replace")
+        if err_over:
+            stderr = stderr.rstrip("\n") + "\n(output truncated)"
+
+        return BashOutput(
+            stdout=stdout,
+            stderr=stderr,
+            exit_code=proc.returncode or 0,
+            timed_out=False,
+            truncated=out_over or err_over,
+        )
+
+    def render_result(self, output: BashOutput) -> str:
+        if output.timed_out:
+            return "Command timed out"
+        parts = [output.stdout]
+        if output.stderr.strip():
+            parts.append(output.stderr)
+        content = "\n".join(p for p in parts if p) or "(no output)"
+        if output.exit_code != 0:
+            content += f"\nExit code: {output.exit_code}"
+        return content

koina-0.1.0/src/koina/tools/edit.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..context import ToolContext
+from ..tool import Tool, ToolError
+
+
+class EditInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    file_path: str = Field(description="The absolute path to the file to modify")
+    old_string: str = Field(description="The text to replace")
+    new_string: str = Field(description="The text to replace it with")
+    replace_all: bool = Field(default=False, description="Replace all occurrences")
+
+
+@dataclass
+class EditOutput:
+    file_path: str
+    replace_all: bool
+    was_created: bool = False
+
+
+class Edit(Tool[EditInput, EditOutput]):
+    name = "Edit"
+    description = "Perform an exact string replacement in a file."
+    Input = EditInput
+
+    async def run(self, input: EditInput, ctx: ToolContext) -> EditOutput:
+        path = Path(input.file_path)
+        if not path.is_absolute():
+            path = ctx.cwd / path
+        if path.suffix == ".ipynb":
+            raise ToolError("Use a notebook editor for .ipynb files")
+
+        if input.old_string == "" and not path.exists():
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(input.new_string, encoding="utf-8", newline="\n")
+            return EditOutput(
+                file_path=str(path), replace_all=input.replace_all, was_created=True
+            )
+
+        if input.old_string == "" and path.exists():
+            raise ToolError(
+                f"File already exists: {input.file_path}; provide a non-empty old_string to edit it"
+            )
+
+        if not path.exists():
+            raise ToolError(f"File does not exist: {input.file_path}")
+
+        text = path.read_text(encoding="utf-8")
+        count = text.count(input.old_string)
+        if count == 0:
+            raise ToolError(f"old_string not found in {input.file_path}")
+        if count > 1 and not input.replace_all:
+            raise ToolError(
+                f"Found {count} matches but replace_all is false; make old_string unique"
+            )
+
+        new_text = text.replace(
+            input.old_string, input.new_string, -1 if input.replace_all else 1
+        )
+        path.write_text(new_text, encoding="utf-8", newline="\n")
+        return EditOutput(file_path=str(path), replace_all=input.replace_all)
+
+    def render_result(self, output: EditOutput) -> str:
+        if output.was_created:
+            return f"File created: {output.file_path}"
+        suffix = " (all occurrences replaced)" if output.replace_all else ""
+        return f"File updated: {output.file_path}{suffix}"

koina-0.1.0/src/koina/tools/glob.py

@@ -0,0 +1,48 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .._ripgrep import run_rg
+from ..context import ToolContext
+from ..tool import Tool
+
+GLOB_LIMIT = 100
+
+
+class GlobInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    pattern: str = Field(description="The glob pattern to match files against")
+    path: str | None = Field(default=None, description="Directory to search in")
+
+
+@dataclass
+class GlobOutput:
+    filenames: list[str]
+    truncated: bool
+
+
+class Glob(Tool[GlobInput, GlobOutput]):
+    name = "Glob"
+    description = "Find files matching a glob pattern, sorted by modification time."
+    Input = GlobInput
+
+    async def run(self, input: GlobInput, ctx: ToolContext) -> GlobOutput:
+        base = Path(input.path) if input.path else ctx.cwd
+        if not base.is_absolute():
+            base = ctx.cwd / base
+        _, stdout = await run_rg(
+            ["--files", "--hidden", "--glob", input.pattern, "--sortr", "modified"],
+            cwd=str(base),
+        )
+        names = [line for line in stdout.splitlines() if line]
+        truncated = len(names) > GLOB_LIMIT
+        return GlobOutput(filenames=names[:GLOB_LIMIT], truncated=truncated)
+
+    def render_result(self, output: GlobOutput) -> str:
+        if not output.filenames:
+            return "No files found"
+        content = "\n".join(output.filenames)
+        if output.truncated:
+            content += "\n(results truncated; use a more specific pattern)"
+        return content

koina-0.1.0/src/koina/tools/grep.py

@@ -0,0 +1,106 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .._ripgrep import run_rg
+from ..context import ToolContext
+from ..tool import Tool
+
+DEFAULT_HEAD_LIMIT = 250
+MAX_COLUMNS = 500
+
+
+class GrepInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+    pattern: str = Field(description="The regular expression to search for")
+    path: str | None = Field(default=None, description="File or directory to search")
+    glob: str | None = Field(default=None, description="Glob to filter files")
+    output_mode: Literal["content", "files_with_matches", "count"] | None = Field(
+        default=None, description="Output mode"
+    )
+    after: int | None = Field(default=None, alias="-A", description="Lines after match")
+    before: int | None = Field(
+        default=None, alias="-B", description="Lines before match"
+    )
+    context: int | None = Field(
+        default=None, alias="-C", description="Lines around match"
+    )
+    line_numbers: bool | None = Field(
+        default=None, alias="-n", description="Show line numbers"
+    )
+    ignore_case: bool | None = Field(
+        default=None, alias="-i", description="Case insensitive"
+    )
+    type: str | None = Field(default=None, description="File type filter")
+    head_limit: int | None = Field(default=None, description="Limit results")
+    offset: int | None = Field(default=None, description="Skip the first N results")
+    multiline: bool | None = Field(default=None, description="Multiline mode")
+
+
+@dataclass
+class GrepOutput:
+    mode: str
+    filenames: list[str]
+    content: str
+
+
+class Grep(Tool[GrepInput, GrepOutput]):
+    name = "Grep"
+    description = "Search file contents with ripgrep."
+    Input = GrepInput
+
+    async def run(self, input: GrepInput, ctx: ToolContext) -> GrepOutput:
+        mode = input.output_mode or "files_with_matches"
+        args: list[str] = []
+        if input.ignore_case:
+            args.append("-i")
+        if input.multiline:
+            args += ["-U", "--multiline-dotall"]
+        if input.glob:
+            args += ["--glob", input.glob]
+        if input.type:
+            args += ["--type", input.type]
+
+        if mode == "files_with_matches":
+            args.append("--files-with-matches")
+        elif mode == "count":
+            args.append("--count")
+        else:
+            args += [
+                "--line-number"
+                if input.line_numbers is not False
+                else "--no-line-number"
+            ]
+            args += ["--max-columns", str(MAX_COLUMNS)]
+            if input.context is not None:
+                args += ["-C", str(input.context)]
+            else:
+                if input.after is not None:
+                    args += ["-A", str(input.after)]
+                if input.before is not None:
+                    args += ["-B", str(input.before)]
+
+        base = Path(input.path) if input.path else ctx.cwd
+        if not base.is_absolute():
+            base = ctx.cwd / base
+        # Run with base as cwd so ripgrep reports paths relative to it (like
+        # Glob), instead of basenames that collide across subdirectories.
+        args += ["--", input.pattern]
+
+        _, stdout = await run_rg(args, cwd=str(base))
+        limit = DEFAULT_HEAD_LIMIT if input.head_limit is None else input.head_limit
+        offset = input.offset or 0
+        lines = [line for line in stdout.splitlines() if line]
+        if offset > 0:
+            lines = lines[offset:]
+        if limit > 0:
+            lines = lines[:limit]
+
+        if mode == "files_with_matches":
+            return GrepOutput(mode=mode, filenames=lines, content="\n".join(lines))
+        return GrepOutput(mode=mode, filenames=[], content="\n".join(lines))
+
+    def render_result(self, output: GrepOutput) -> str:
+        return output.content or "No matches found"

koina-0.1.0/src/koina/tools/read.py

@@ -0,0 +1,88 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..context import ToolContext
+from ..tool import Tool, ToolError
+
+
+class ReadInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    file_path: str = Field(description="The absolute path to the file to read")
+    offset: int | None = Field(default=None, ge=1, description="1-based start line")
+    limit: int | None = Field(default=None, ge=1, description="Number of lines to read")
+
+
+@dataclass
+class ReadOutput:
+    content: str
+    start_line: int
+    num_lines: int
+    truncated: bool
+
+
+class Read(Tool[ReadInput, ReadOutput]):
+    name = "Read"
+    description = (
+        "Read a text file from the local filesystem. Lines are returned numbered."
+    )
+    Input = ReadInput
+
+    async def run(self, input: ReadInput, ctx: ToolContext) -> ReadOutput:
+        path = Path(input.file_path)
+        if not path.is_absolute():
+            path = ctx.cwd / path
+        if not path.exists():
+            raise ToolError(f"File does not exist: {input.file_path}")
+        if not path.is_file():
+            raise ToolError(f"Not a regular file: {input.file_path}")
+
+        byte_budget = min(ctx.read_limits.max_bytes, ctx.read_limits.max_tokens * 4)
+        with path.open("rb") as fh:
+            data = fh.read(byte_budget + 1)
+        truncated = len(data) > byte_budget
+        if truncated:
+            data = data[:byte_budget]
+
+        text = data.decode("utf-8", errors="replace")
+        lines = text.split("\n")
+        if lines and lines[-1] == "":
+            lines = lines[:-1]
+
+        if len(lines) == 0:
+            return ReadOutput(
+                content="(file is empty)",
+                start_line=1,
+                num_lines=0,
+                truncated=truncated,
+            )
+
+        start = input.offset if input.offset and input.offset > 0 else 1
+        if start > len(lines):
+            return ReadOutput(
+                content=f"(offset {start} is beyond end of file: {len(lines)} lines)",
+                start_line=start,
+                num_lines=0,
+                truncated=truncated,
+            )
+
+        end = (
+            len(lines)
+            if input.limit is None
+            else min(len(lines), start - 1 + input.limit)
+        )
+        selected = lines[start - 1 : end]
+        numbered = "\n".join(f"{start + i}\t{line}" for i, line in enumerate(selected))
+        return ReadOutput(
+            content=numbered,
+            start_line=start,
+            num_lines=len(selected),
+            truncated=truncated,
+        )
+
+    def render_result(self, output: ReadOutput) -> str:
+        content = output.content
+        if output.truncated:
+            content += "\n(file truncated: exceeded max_bytes)"
+        return content

koina-0.1.0/src/koina/tools/write.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..context import ToolContext
+from ..tool import Tool
+
+
+class WriteInput(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    file_path: str = Field(description="The absolute path to the file to write")
+    content: str = Field(description="The content to write to the file")
+
+
+@dataclass
+class WriteOutput:
+    kind: Literal["create", "update"]
+    file_path: str
+
+
+class Write(Tool[WriteInput, WriteOutput]):
+    name = "Write"
+    description = "Write a file to the local filesystem, overwriting if it exists."
+    Input = WriteInput
+
+    async def run(self, input: WriteInput, ctx: ToolContext) -> WriteOutput:
+        path = Path(input.file_path)
+        if not path.is_absolute():
+            path = ctx.cwd / path
+        kind: Literal["create", "update"] = "update" if path.exists() else "create"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        normalized = input.content.replace("\r\n", "\n").replace("\r", "\n")
+        path.write_text(normalized, encoding="utf-8", newline="\n")
+        return WriteOutput(kind=kind, file_path=str(path))
+
+    def render_result(self, output: WriteOutput) -> str:
+        verb = "created successfully at:" if output.kind == "create" else "updated:"
+        return f"File {verb} {output.file_path}"