Skip to content
Python
9.6 KB
Raw Blame
"""Vetted tool catalog — the stable ``id → capability`` layer a persona references.

A *capability* bundles a group of tools (the existing ``tools/`` factories) behind a stable
id, plus what session context it needs (``requires``) and the risk classes it can produce
(``risk``, used by the Phase 2 install-consent screen). ``expand(ids, context)`` turns a
persona's ``tools:`` list into concrete callables, skipping capabilities whose context
prerequisites aren't met (e.g. no shell without an executor) — matching the per-agent
factories that used to assemble tools by hand.

The catalog is **platform-owned and closed**: third parties get breadth from us adding
vetted capabilities here and from MCP, never by adding entries. MCP tools are *not* in the
catalog (see ``PERMISSIONS-AND-INBOX.md``).
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Callable

import aisuite as ai

from .agents.base import AgentContext
from .risk import RiskClass
from .sandbox.proxy import proxy_tools
from .tools.files import file_tools
from .tools.git import git_tools
from .tools.search import search_tools
from .tools.shell import shell_tools
from .tools.todo import todo_tools

# Context prerequisites a capability may require, mapped to a predicate over AgentContext.
_REQUIREMENTS: dict[str, Callable[[AgentContext], bool]] = {
    "workspace": lambda c: c.workspace is not None,
    "executor": lambda c: c.executor is not None,
    "todo": lambda c: c.todo is not None,
}


@dataclass(frozen=True)
class Capability:
    id: str
    name: str  # human label (consent screen)
    description: str
    build: Callable[[AgentContext], list]
    requires: tuple[str, ...] = ()
    risk: tuple[RiskClass, ...] = (RiskClass.READ,)

    def available(self, context: AgentContext) -> bool:
        return all(_REQUIREMENTS[r](context) for r in self.requires)


# -- capability builders --------------------------------------------------------
# These reproduce, exactly, what the Code and Cowork agent factories assembled by hand.

# OPE-186 change 2: aisuite's file tools describe themselves in one generic line each
# ("Write a UTF-8 text file under the configured root."), so nothing tells the model when
# to rewrite a file and when to edit it. In one long multi-task session Kimi K3 chose
# write_file 1,812 times against 609 targeted edits, and every whole-file body it wrote
# rode along in the conversation on every later turn. Building the guidance into the
# tool description is the usual remedy; these descriptions do that.
EDIT_TOOL_GUIDANCE: dict[str, str] = {
    "write_file": (
        "Create a NEW file, or replace an existing file's ENTIRE content when most of it "
        "changes. For a small or medium change to an existing file do not rewrite it: read "
        "it, then use replace_in_file (exact text swap) or apply_patch (multi-line edit). "
        "The whole `content` you pass stays in the conversation on every later turn, so "
        "whole-file rewrites of large files are expensive."
    ),
    "replace_in_file": (
        "Edit an existing file in place: replace `old` (an exact, unique text fragment, "
        "whitespace included) with `new`. Prefer this over write_file for changing part of "
        "a file; read the file first so `old` matches exactly. Set expected_replacements "
        "when the fragment appears more than once."
    ),
    "apply_patch": (
        "Apply a Codex-style patch (*** Begin Patch / *** Update File: path / @@ hunks of "
        "' ' context, '-' removed and '+' added lines / *** End Patch) for targeted "
        "multi-line edits to one or more existing files, or to add or delete files. Prefer "
        "this over write_file for edits that touch several places."
    ),
    "apply_unified_diff": (
        "Apply a standard unified diff (the format of `diff -u` or `git diff`) to existing "
        "files. Use it when you already have the change as a diff."
    ),
}


def _describe_edit_tools(tools: list) -> list:
    """Give the file tools descriptions that say WHEN to use each (the registry builds the
    schema the model sees from the docstring)."""
    for t in tools:
        text = EDIT_TOOL_GUIDANCE.get(getattr(t, "__name__", ""))
        if text:
            try:
                t.__doc__ = text
            except (AttributeError, TypeError):
                pass
    return tools


def _placed(context: AgentContext, tools: list) -> list:
    """Where the workspace tools run. In `direct` mode (and whenever the session has no tool
    runner) they are returned untouched. With a runner, each is replaced by a proxy that has
    the same definition and sends only the execution into the sandbox."""
    sandbox = context.sandbox
    if sandbox is None or getattr(sandbox, "client", None) is None:
        return tools
    return proxy_tools(tools, sandbox, root=str(context.workspace), roots=context.roots)


def _code_files(context: AgentContext) -> list:
    """Repo-oriented files: line-numbered/windowed `read_file`. Our `grep` and windowed
    `read_file` replace aisuite's slower `search_files` / `read_file`/`read_file_lines`,
    and our folder-aware `list_files` replaces the toolkit's files-only one (OPE-203).
    Multi-root aware (universal scratch): with session roots, writes/reads reach the
    scratch and granted dirs too; the workspace stays the relative-path anchor.
    """
    ws = str(context.workspace)
    replaced = {"search_files", "read_file", "read_file_lines", "list_files"}
    file_kwargs = (
        {"roots": context.roots} if context.roots else {"root": ws, "allow_write": True}
    )
    files = _describe_edit_tools(
        [
            t
            for t in ai.toolkits.files(**file_kwargs)
            if getattr(t, "__name__", "") not in replaced
        ]
    )
    return _placed(context, [*files, *file_tools(ws, roots=context.roots)])


def _files(context: AgentContext) -> list:
    """Knowledge-work files: multi-root aware (reads/writes across the session's roots).
    One reader everywhere (owner ruling 2026-08-20): the windowed, line-numbered
    `read_file` replaces aisuite's `read_file`/`read_file_lines`, our `grep`
    replaces the slow `search_files`, and our folder-aware `list_files` replaces the
    toolkit's files-only one (OPE-203) — same set Code uses.
    """
    ws = str(context.workspace)
    file_kwargs = (
        {"roots": context.roots} if context.roots else {"root": ws, "allow_write": True}
    )
    replaced = {"search_files", "read_file", "read_file_lines", "list_files"}
    files = _describe_edit_tools(
        [
            t
            for t in ai.toolkits.files(**file_kwargs)
            if getattr(t, "__name__", "") not in replaced
        ]
    )
    return _placed(context, [*files, *file_tools(ws, roots=context.roots)])


def _git(context: AgentContext) -> list:
    ws = str(context.workspace)
    return _placed(context, [*ai.toolkits.git(root=ws), *git_tools(ws)])  # git_status, git_diff, git_log


def _search(context: AgentContext) -> list:
    return _placed(context, search_tools(str(context.workspace)))  # grep (ripgrep, .gitignore-aware)


def _shell(context: AgentContext) -> list:
    return shell_tools(context.executor)  # run_shell + background task tools


def _todo(context: AgentContext) -> list:
    return todo_tools(context.todo)  # todo_write (drives the Progress panel)


_CAPS: list[Capability] = [
    Capability(
        id="code_files",
        name="Code files",
        description="Read & edit files in a single repo workspace (line-numbered reads).",
        build=_code_files,
        requires=("workspace",),
        risk=(RiskClass.READ, RiskClass.WRITE_LOCAL),
    ),
    Capability(
        id="files",
        name="Files",
        description="Read & edit files across the session's workspace folders.",
        build=_files,
        requires=("workspace",),
        risk=(RiskClass.READ, RiskClass.WRITE_LOCAL),
    ),
    Capability(
        id="git",
        name="Git",
        description="Inspect git state and history (status, diff, log).",
        build=_git,
        requires=("workspace",),
        risk=(RiskClass.READ,),
    ),
    Capability(
        id="search",
        name="Search",
        description="Fast code/content search (grep).",
        build=_search,
        requires=("workspace",),
        risk=(RiskClass.READ,),
    ),
    Capability(
        id="shell",
        name="Shell",
        description="Run shell commands in a persistent session.",
        build=_shell,
        requires=("executor",),
        risk=(RiskClass.EXEC,),
    ),
    Capability(
        id="todo",
        name="Task list",
        description="Maintain a visible task/progress list.",
        build=_todo,
        requires=("todo",),
        risk=(RiskClass.READ,),
    ),
]

CATALOG: dict[str, Capability] = {c.id: c for c in _CAPS}


def capability(cap_id: str) -> Capability:
    cap = CATALOG.get(cap_id)
    if cap is None:
        raise KeyError(f"Unknown capability id: {cap_id!r}")
    return cap


def expand(ids: list[str], context: AgentContext) -> list:
    """Expand a persona's ``tools:`` id list into concrete tool callables for this context.
    Capabilities whose context prerequisites aren't met are skipped (no shell without an
    executor, no files without a workspace) — exactly like the old hand-written factories.
    """
    tools: list = []
    for cap_id in ids:
        cap = capability(cap_id)
        if cap.available(context):
            tools.extend(cap.build(context))
    return tools


def risk_summary(ids: list[str]) -> set[RiskClass]:
    """The union of risk classes a tool list can produce — for the install-consent screen."""
    out: set[RiskClass] = set()
    for cap_id in ids:
        out.update(capability(cap_id).risk)
    return out