avo 0.1.0__py3-none-any.whl

avo/__init__.py

@@ -0,0 +1,53 @@
+"""Public API for Avo 0.1."""
+
+from avo.events import AgentEvent, EventType
+from avo.integrations import LetheMemoryAdapter, MemoryProvider
+from avo.models import (
+    Checkpoint,
+    ModelRequest,
+    ModelResponse,
+    RunRecord,
+    RunResult,
+    TokenUsage,
+    ToolCall,
+    ToolMetadata,
+    ToolResult,
+)
+from avo.policies import LoopPolicy
+from avo.progress import ProgressDetector
+from avo.providers.fake import FakeProvider, ScriptItem
+from avo.runtime import AgentRuntime
+from avo.state import RunState, StopReason
+from avo.tools import FunctionTool, Tool, ToolRegistry
+from avo.tracing import RunTrace, TraceEntry, TraceInspector
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentEvent",
+    "AgentRuntime",
+    "Checkpoint",
+    "EventType",
+    "FakeProvider",
+    "FunctionTool",
+    "LetheMemoryAdapter",
+    "LoopPolicy",
+    "MemoryProvider",
+    "ModelRequest",
+    "ModelResponse",
+    "ProgressDetector",
+    "RunRecord",
+    "RunResult",
+    "RunState",
+    "RunTrace",
+    "ScriptItem",
+    "StopReason",
+    "TokenUsage",
+    "Tool",
+    "ToolCall",
+    "ToolMetadata",
+    "ToolRegistry",
+    "ToolResult",
+    "TraceEntry",
+    "TraceInspector",
+]

avo/_pytest_plugin.py

@@ -0,0 +1,58 @@
+"""pytest plugin entry point that registers the ``--run-live`` flag.
+
+Registered via ``pyproject.toml`` ``entry_points`` so ``pytest --run-live``
+becomes a first-class CLI option without needing a ``conftest.py`` at
+the repo root. Without the flag the integration tests stay skipped by
+the ``--ignore`` default in ``[tool.pytest.ini_options]`` — this hook
+re-enables them when the operator opts in.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Locate the integration test directory *relative to this plugin* so the
+# plugin works regardless of pytest's rootdir resolution.
+INTEGRATION_DIR = Path(__file__).resolve().parent.parent.parent / "tests" / "integration"
+
+
+def pytest_addoption(parser: object) -> None:
+    """Register ``--run-live`` so opt-in integration tests can be enabled."""
+
+    group = getattr(parser, "getgroup", lambda _name: parser)("avo")
+    add_option = getattr(group, "addoption", None)
+    if add_option is None:  # pragma: no cover - argparse fallback path
+        add_option = parser.add_option  # type: ignore[attr-defined]
+    add_option(
+        "--run-live",
+        action="store_true",
+        default=False,
+        help="Run live HTTP integration tests against real provider endpoints.",
+    )
+
+
+def pytest_collection_modifyitems(config: object, items: list[object]) -> None:
+    """Skip live tests unless ``--run-live`` was passed."""
+
+    run_live = bool(getattr(config, "getoption", lambda _n: False)("--run-live"))
+    if run_live:
+        return
+    skip = _build_skipper()
+    for item in items:
+        path = getattr(item, "fspath", None) or getattr(item, "path", None)
+        if path is None:
+            continue
+        try:
+            is_integration = INTEGRATION_DIR in Path(str(path)).resolve().parents
+        except OSError:  # pragma: no cover
+            is_integration = False
+        if is_integration:
+            mark = getattr(item, "add_marker", None)
+            if mark is not None:
+                mark(skip)
+
+
+def _build_skipper() -> object:
+    import pytest
+
+    return pytest.mark.skip(reason="--run-live not enabled; offline suite skips live tests")

avo/app_tools/__init__.py

@@ -0,0 +1,14 @@
+"""Application tools: workspace sandboxing, shell execution, and approval.
+
+Application tools build on the existing ``FunctionTool`` / ``ToolRegistry``
+contract documented in ``src/avo/tools.py``. They do not modify
+``AgentRuntime`` or the state machine; they plug in via the existing
+``approval_callback`` parameter on ``AgentRuntime``.
+
+The sandbox module is optional and lives behind the ``[sandbox]`` extra in
+``pyproject.toml`` because it requires the ``docker`` package.
+"""
+
+from __future__ import annotations
+
+__all__ = []

avo/app_tools/approval.py

@@ -0,0 +1,98 @@
+"""Approval policy builder for application tools.
+
+The runtime invokes ``approval_callback(call)`` while in the
+``APPROVAL_PENDING`` state (see ``src/avo/runtime.py`` and the
+state-machine reference). This module produces a callable that consults
+the ``AVO_TOOLS_REQUIRE_APPROVAL`` environment variable to decide
+which tool names must wait for explicit operator approval.
+
+The variable is a comma- or whitespace-separated list of tool names.
+Tool names not present are auto-approved without invoking any
+callback machinery.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Awaitable, Callable
+from typing import Protocol
+
+from avo.models import ToolCall
+
+
+class ApprovalDecision(Protocol):
+    """A user-provided callable that returns True to approve a tool call."""
+
+    def __call__(self, call: ToolCall) -> bool | Awaitable[bool]: ...
+
+
+def _parse_env_list(environ: os._Environ[str] | dict[str, str]) -> set[str]:
+    """Parse ``AVO_TOOLS_REQUIRE_APPROVAL`` into a normalized name set."""
+
+    raw = environ.get("AVO_TOOLS_REQUIRE_APPROVAL", "")
+    if not raw:
+        return set()
+    tokens: list[str] = []
+    for chunk in raw.replace("\n", ",").split(","):
+        tokens.extend(chunk.split())
+    return {name.strip() for name in tokens if name.strip()}
+
+
+def build_approval_callback(
+    environ: os._Environ[str] | dict[str, str] | None = None,
+    *,
+    on_require: Callable[[ToolCall], None] | None = None,
+) -> ApprovalDecision:
+    """Build an ``approval_callback`` that consults ``AVO_TOOLS_REQUIRE_APPROVAL``.
+
+    Args:
+        environ: Mapping to read from. Defaults to ``os.environ``.
+        on_require: Optional callback invoked whenever a tool requires
+            approval. The runtime-supplied approval callback may be a
+            coroutine; the operator-supplied one returned here is always
+            synchronous.
+
+    Behavior:
+        - Tool names listed in ``AVO_TOOLS_REQUIRE_APPROVAL`` → return
+          ``False`` so the runtime stops the run with ``POLICY_DENIED``.
+          This matches the documented behavior of a synchronous denial —
+          the operator is expected to gate the actual decision outside the
+          runtime. (The runtime treats ``False`` as denial.)
+        - Tool names not in the list → return ``True`` immediately.
+
+    Notes:
+        For 0.1 this returns ``False`` rather than raising so the
+        runtime stops deterministically. Operators wanting to inject a
+        real interactive prompt can wrap this callback with their own
+        ``on_require`` to escalate.
+    """
+
+    env: os._Environ[str] | dict[str, str] = os.environ if environ is None else environ
+    required = _parse_env_list(env)
+
+    def _callback(call: ToolCall) -> bool:
+        if call.name not in required:
+            return True
+        if on_require is not None:
+            on_require(call)
+        # 0.1 behavior: required tools are denied. Operators wanting
+        # interactive approval must wrap this callback.
+        return False
+
+    return _callback
+
+
+def required_tool_names(
+    environ: os._Environ[str] | dict[str, str] | None = None,
+) -> set[str]:
+    """Return the parsed set of tool names that require approval."""
+
+    env: os._Environ[str] | dict[str, str] = os.environ if environ is None else environ
+    return _parse_env_list(env)
+
+
+__all__ = [
+    "ApprovalDecision",
+    "build_approval_callback",
+    "required_tool_names",
+]

avo/app_tools/edit_file.py

@@ -0,0 +1,130 @@
+"""``edit_file`` tool: surgical string replacement inside a file.
+
+Like ``write_file``, the path is resolved through the active
+:class:`Workspace` and the write itself opens the file with
+``O_NOFOLLOW`` to refuse symlink targets. Unlike ``write_file``, this
+tool only changes the matching region and is safe for the model to use
+on partial edits without rewriting the whole file.
+
+Behaviour:
+
+* ``replace_all=False`` (default) requires exactly one match of
+  ``old_string``. Zero matches and multiple matches both raise
+  :class:`EditFileError` with a precise reason.
+* ``replace_all=True`` replaces every non-overlapping match. Zero
+  matches still raises — a no-op edit should not silently succeed.
+* ``old_string`` and ``new_string`` must differ.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+from avo import FunctionTool as PublicFunctionTool
+
+from .file_tools import _workspace_stack
+from .workspace import Workspace
+
+
+class EditFileError(RuntimeError):
+    """Raised when ``edit_file`` cannot satisfy the requested edit."""
+
+
+class EditFileArguments(BaseModel):
+    """Arguments for the ``edit_file`` tool."""
+
+    path: str = Field(min_length=1, description="Workspace-relative or absolute path")
+    old_string: str = Field(min_length=1, description="Literal text to replace")
+    new_string: str = Field(description="Replacement text")
+    replace_all: bool = Field(
+        default=False,
+        description="Replace every match; otherwise the match must be unique",
+    )
+
+    @model_validator(mode="after")
+    def _require_difference(self) -> EditFileArguments:
+        """Reject edits where replacement equals the original text."""
+
+        if self.old_string == self.new_string:
+            raise ValueError("old_string and new_string must differ")
+        return self
+
+
+def _current_edit_workspace() -> Workspace:
+    if not _workspace_stack:
+        raise EditFileError(
+            "edit_file invoked without an active workspace; wrap the run in "
+            "avo.app_tools.file_tools.bind_workspace(...)"
+        )
+    return _workspace_stack[-1]
+
+
+def _apply_edit(text: str, old_string: str, new_string: str, replace_all: bool) -> str:
+    """Return ``text`` with ``old_string`` replaced by ``new_string``.
+
+    Raises:
+        EditFileError: when ``old_string`` does not appear, or appears
+            more than once and ``replace_all=False``.
+    """
+
+    occurrences = text.count(old_string)
+    if occurrences == 0:
+        raise EditFileError("old_string not found in file")
+    if occurrences > 1 and not replace_all:
+        raise EditFileError(
+            f"old_string matches {occurrences} locations; pass replace_all=True "
+            "to replace all matches, or narrow old_string to a single location"
+        )
+    return text.replace(old_string, new_string)
+
+
+async def _edit_file(arguments: EditFileArguments) -> dict[str, Any]:
+    workspace = _current_edit_workspace()
+    resolved = workspace.validate_for_write(arguments.path)
+    encoding = "utf-8"
+    original_text = resolved.read_text(encoding=encoding)
+
+    updated_text = _apply_edit(
+        original_text, arguments.old_string, arguments.new_string, arguments.replace_all
+    )
+
+    encoded = updated_text.encode(encoding)
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    fd = os.open(resolved, flags, 0o644)
+    try:
+        os.write(fd, encoded)
+    finally:
+        os.close(fd)
+    return {
+        "path": str(resolved),
+        "size": len(encoded),
+        "matches_replaced": original_text.count(arguments.old_string),
+    }
+
+
+def edit_file_tool() -> PublicFunctionTool[EditFileArguments]:
+    """Return a :class:`FunctionTool` that performs a surgical file edit."""
+
+    return PublicFunctionTool(
+        name="edit_file",
+        description=(
+            "Replace a literal string in a file inside the workspace. By "
+            "default the match must be unique; pass replace_all=True to "
+            "replace every occurrence. The path is validated against the "
+            "workspace and the write refuses to follow symlinks."
+        ),
+        arguments_model=EditFileArguments,
+        function=_edit_file,
+    )
+
+
+__all__ = [
+    "EditFileArguments",
+    "EditFileError",
+    "edit_file_tool",
+]

avo/app_tools/file_tools.py

@@ -0,0 +1,145 @@
+"""``read_file`` and ``write_file`` tools bound to a fixed workspace.
+
+Both tools resolve the model-supplied path through
+:class:`avo.app_tools.workspace.Workspace` before any I/O. The
+returned :class:`FunctionTool` instances plug into
+``AgentRuntime(tools=[...])`` without any change to the runtime itself.
+
+Approval and timeout policy are configured at the ``AgentRuntime`` level
+via ``approval_callback=`` and ``LoopPolicy.tool_timeout_seconds=``. This
+module does **not** introduce its own timeout or approval mechanism.
+
+The workspace itself is bound per call site via :func:`bind_workspace`,
+which keeps the tools stateless across runs and avoids relying on
+thread-locals or mutable module state that a hostile prompt could
+mutate.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from avo import FunctionTool as PublicFunctionTool
+
+from .workspace import Workspace
+
+
+class ReadFileArguments(BaseModel):
+    """Arguments for the ``read_file`` tool."""
+
+    path: str = Field(min_length=1, description="Workspace-relative or absolute path")
+    encoding: str = Field(default="utf-8", min_length=1)
+
+
+class WriteFileArguments(BaseModel):
+    """Arguments for the ``write_file`` tool."""
+
+    path: str = Field(min_length=1, description="Workspace-relative or absolute path")
+    content: str = Field(description="Full file content to write")
+    encoding: str = Field(default="utf-8", min_length=1)
+
+
+class WorkspaceNotBoundError(RuntimeError):
+    """Raised when a file tool is invoked without an active workspace binding."""
+
+
+_workspace_stack: list[Workspace] = []
+
+
+@contextmanager
+def bind_workspace(workspace: Workspace) -> Generator[None, None, None]:
+    """Push ``workspace`` onto the active binding for the duration of the block."""
+
+    _workspace_stack.append(workspace)
+    try:
+        yield
+    finally:
+        _workspace_stack.pop()
+
+
+def _current_workspace() -> Workspace:
+    if not _workspace_stack:
+        raise WorkspaceNotBoundError(
+            "file tool invoked without an active workspace; wrap the run in "
+            "avo.app_tools.file_tools.bind_workspace(...)"
+        )
+    return _workspace_stack[-1]
+
+
+async def _read_file(arguments: ReadFileArguments) -> dict[str, Any]:
+    workspace = _current_workspace()
+    resolved = workspace.validate_path(arguments.path, must_exist=True)
+    text = resolved.read_text(encoding=arguments.encoding)
+    return {
+        "path": str(resolved),
+        "size": len(text.encode(arguments.encoding)),
+        "content": text,
+    }
+
+
+async def _write_file(arguments: WriteFileArguments) -> dict[str, Any]:
+    workspace = _current_workspace()
+    resolved = workspace.validate_for_write(arguments.path)
+    encoded = arguments.content.encode(arguments.encoding)
+    # Open the leaf explicitly, refusing to follow symlinks at the leaf so
+    # a model cannot redirect a write to an external target after the
+    # workspace check. O_NOFOLLOW is POSIX-only; on Windows we accept the
+    # residual TOCTOU window.
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    fd = os.open(resolved, flags, 0o644)
+    try:
+        os.write(fd, encoded)
+    finally:
+        os.close(fd)
+    return {
+        "path": str(resolved),
+        "size": len(encoded),
+    }
+
+
+def read_file_tool() -> PublicFunctionTool[ReadFileArguments]:
+    """Return a :class:`FunctionTool` that reads a file inside the active workspace."""
+
+    return PublicFunctionTool(
+        name="read_file",
+        description=(
+            "Read the full content of a file inside the workspace. Paths "
+            "are resolved against the workspace root; any traversal "
+            "outside the workspace is rejected before the file is opened."
+        ),
+        arguments_model=ReadFileArguments,
+        function=_read_file,
+    )
+
+
+def write_file_tool() -> PublicFunctionTool[WriteFileArguments]:
+    """Return a :class:`FunctionTool` that writes a file inside the active workspace."""
+
+    return PublicFunctionTool(
+        name="write_file",
+        description=(
+            "Write content to a file inside the workspace, creating the "
+            "file if necessary. Existing files are overwritten. Paths "
+            "are resolved against the workspace root; any traversal "
+            "outside the workspace is rejected before the file is opened."
+        ),
+        arguments_model=WriteFileArguments,
+        function=_write_file,
+    )
+
+
+__all__ = [
+    "ReadFileArguments",
+    "WorkspaceNotBoundError",
+    "WriteFileArguments",
+    "bind_workspace",
+    "read_file_tool",
+    "write_file_tool",
+]

avo/app_tools/git_status.py

@@ -0,0 +1,80 @@
+"""``git_status`` tool — surface repository state to the model.
+
+The tool binds to the active :class:`Workspace` and walks up to the
+nearest git working tree. Path traversal is rejected at construction;
+the tool only ever returns paths inside the workspace root.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from avo import FunctionTool as PublicFunctionTool
+
+from ..workspace.git import GitRepository, GitStatus
+from .edit_file import EditFileError
+from .file_tools import _workspace_stack
+from .workspace import Workspace
+
+_DEFAULT_MAX_FILES = 20
+
+
+class GitStatusArguments(BaseModel):
+    """Arguments for the ``git_status`` tool."""
+
+    include_untracked: bool = Field(default=True)
+    max_files: int = Field(default=_DEFAULT_MAX_FILES, gt=0, le=500)
+
+
+def _current_workspace() -> Workspace:
+    if not _workspace_stack:
+        raise EditFileError(
+            "git_status invoked without an active workspace; wrap the run in "
+            "avo.app_tools.file_tools.bind_workspace(...)"
+        )
+    return _workspace_stack[-1]
+
+
+def _summarise(status: GitStatus, arguments: GitStatusArguments) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "root": str(status.root),
+        "branch": status.branch,
+        "clean": status.clean,
+        "modified_count": len(status.modified),
+        "untracked_count": len(status.untracked),
+    }
+    if arguments.include_untracked:
+        payload["untracked"] = list(status.untracked[: arguments.max_files])
+    payload["modified"] = list(status.modified[: arguments.max_files])
+    payload["truncated"] = len(status.modified) > arguments.max_files
+    return payload
+
+
+async def _git_status(arguments: GitStatusArguments) -> dict[str, Any]:
+    workspace = _current_workspace()
+    repo = GitRepository(workspace.root)
+    status = repo.status()
+    return _summarise(status, arguments)
+
+
+def git_status_tool() -> PublicFunctionTool[GitStatusArguments]:
+    """Return a :class:`FunctionTool` that surfaces git state."""
+
+    return PublicFunctionTool(
+        name="git_status",
+        description=(
+            "Return the git status of the active workspace — branch, "
+            "modified files, and (optionally) untracked files. Read-only."
+        ),
+        arguments_model=GitStatusArguments,
+        function=_git_status,
+    )
+
+
+__all__ = ["GitStatusArguments", "git_status_tool"]
+
+
+_ = Path  # re-export for type checker

avo/app_tools/glob_tool.py

@@ -0,0 +1,96 @@
+"""``glob`` tool: enumerate workspace files matching a pattern.
+
+The tool resolves ``path`` against the active :class:`Workspace`,
+rejects any traversal, then walks with :meth:`pathlib.Path.glob` (or
+:meth:`rglob` when ``recursive=True``). Results are returned as paths
+relative to the workspace root so the model never sees absolute
+locations outside the workspace.
+
+Output is sorted and capped at ``max_results`` (default 200) so a
+generous pattern cannot flood the context window.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from avo import FunctionTool as PublicFunctionTool
+
+from .edit_file import EditFileError  # reuse the workspace-binding contract
+from .file_tools import _workspace_stack
+from .workspace import Workspace
+
+_DEFAULT_MAX_RESULTS = 200
+
+
+class GlobArguments(BaseModel):
+    """Arguments for the ``glob`` tool."""
+
+    pattern: str = Field(min_length=1, description="Glob pattern, e.g. ``**/*.py``")
+    path: str = Field(
+        default=".",
+        description="Workspace-relative or absolute directory to search in",
+    )
+    recursive: bool = Field(default=True)
+    max_results: int = Field(default=_DEFAULT_MAX_RESULTS, gt=0, le=10_000)
+
+
+def _current_glob_workspace() -> Workspace:
+    if not _workspace_stack:
+        raise EditFileError(
+            "glob invoked without an active workspace; wrap the run in "
+            "avo.app_tools.file_tools.bind_workspace(...)"
+        )
+    return _workspace_stack[-1]
+
+
+async def _glob(arguments: GlobArguments) -> dict[str, Any]:
+    workspace = _current_glob_workspace()
+    base = workspace.validate_path(arguments.path, must_exist=True)
+    if not base.is_dir():
+        raise EditFileError(f"glob path is not a directory: {arguments.path}")
+
+    walker = base.rglob if arguments.recursive else base.glob
+    matches = sorted(walker(arguments.pattern))
+
+    relative: list[str] = []
+    truncated = False
+    for candidate in matches:
+        if not candidate.is_file() and not candidate.is_dir():
+            continue
+        try:
+            relative_path = candidate.resolve().relative_to(workspace.root)
+        except ValueError as exc:  # pragma: no cover - guarded by validate_path
+            raise EditFileError(f"escape detected: {candidate}") from exc
+        if len(relative) >= arguments.max_results:
+            truncated = True
+            break
+        relative.append(relative_path.as_posix())
+
+    return {
+        "pattern": arguments.pattern,
+        "base": str(base),
+        "count": len(relative),
+        "truncated": truncated,
+        "matches": relative,
+    }
+
+
+def glob_tool() -> PublicFunctionTool[GlobArguments]:
+    """Return a :class:`FunctionTool` that enumerates workspace files."""
+
+    return PublicFunctionTool(
+        name="glob",
+        description=(
+            "List files inside the workspace matching a glob pattern (e.g. "
+            "``**/*.py``). Paths are returned relative to the workspace root; "
+            "any traversal that escapes the root is rejected before the walk."
+        ),
+        arguments_model=GlobArguments,
+        function=_glob,
+    )
+
+
+__all__ = ["GlobArguments", "glob_tool"]