pcli-agent 0.1.0__py3-none-any.whl

pcli/tools/pydiscovery/search.py

@@ -0,0 +1,117 @@
+"""search_python: coarse, in-process, name/summary-only search (tier 1) —
+safe, no imports, no permission needed.
+
+inspect_python_module: imports one specific module to list its public
+functions/classes (tier 2) — this DOES import third-party code, so it's
+permission-gated and runs through invoke.run_bootstrap's isolated subprocess.
+"""
+
+from __future__ import annotations
+
+from pcli.tools.base import ToolContext, ToolResult, ToolSpec
+from pcli.tools.pydiscovery.cache import load_or_build_index
+from pcli.tools.pydiscovery.invoke import run_bootstrap
+
+_MAX_RESULTS = 50
+
+
+async def _search_python(arguments: dict, ctx: ToolContext) -> ToolResult:
+    query = arguments.get("query", "").strip().lower()
+    entries = load_or_build_index()
+    matches = [
+        e for e in entries if not query or query in e.name.lower() or query in e.summary.lower()
+    ]
+
+    if not matches:
+        return ToolResult(output="No matching modules/packages found.")
+
+    lines = [f"{e.name} - {e.summary}" if e.summary else e.name for e in matches[:_MAX_RESULTS]]
+    text = "\n".join(lines)
+    if len(matches) > _MAX_RESULTS:
+        text += f"\n[...{len(matches) - _MAX_RESULTS} more matches not shown, narrow your query...]"
+    text += (
+        "\n\n(Name/summary index only — nothing was imported. Use inspect_python_module to "
+        "see the functions/classes inside a specific module.)"
+    )
+    return ToolResult(output=text)
+
+
+SEARCH_PYTHON = ToolSpec(
+    name="search_python",
+    description="Search installed Python packages/modules (stdlib + site-packages) by name or "
+    "summary, without importing anything. Use this first to find candidate modules, then "
+    "inspect_python_module to see what's inside one.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "Keyword(s) to match against module names and package summaries. "
+                "Empty string lists everything.",
+            }
+        },
+        "required": ["query"],
+    },
+    handler=_search_python,
+    needs_permission=False,
+    plan_mode_safe=True,
+    read_only=True,
+)
+
+
+async def _inspect_python_module(arguments: dict, ctx: ToolContext) -> ToolResult:
+    module = arguments["module"]
+    payload = {"mode": "inspect", "module": module, "query": arguments.get("query", "")}
+    try:
+        data = await run_bootstrap(ctx, payload)
+    except RuntimeError as exc:
+        return ToolResult(
+            output=f"Failed to inspect module '{module}': {exc}\n"
+            "[pcli] Suggestion: run search_python first to confirm the exact module name is "
+            "actually installed.",
+            is_error=True,
+        )
+
+    if not data.get("ok"):
+        return ToolResult(
+            output=f"{data.get('error', 'unknown error')}\n"
+            "[pcli] Suggestion: run search_python first to confirm the exact module name is "
+            "actually installed.",
+            is_error=True,
+        )
+
+    members = data["members"]
+    if not members:
+        return ToolResult(output=f"No matching members found in module '{module}'.")
+    lines = [
+        f"{m['kind']} {m['name']}{m['signature']}" + (f" - {m['doc']}" if m["doc"] else "")
+        for m in members
+    ]
+    return ToolResult(output="\n".join(lines))
+
+
+INSPECT_PYTHON_MODULE = ToolSpec(
+    name="inspect_python_module",
+    description="Import and introspect a specific Python module to see its public functions "
+    "and classes (name, signature, one-line docstring). This actually imports the module "
+    "(in an isolated subprocess), so use search_python first to find the right module name.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "module": {
+                "type": "string",
+                "description": "Fully-qualified module name to import, e.g. 'json' or "
+                "'xml.etree.ElementTree'.",
+            },
+            "query": {"type": "string", "description": "Optional keyword to filter member names."},
+        },
+        "required": ["module"],
+    },
+    handler=_inspect_python_module,
+    needs_permission=True,
+    needs_sandbox=True,
+    risk_description="Imports a Python module, which may execute module-level side effects.",
+    guardrail_python_module_arg="module",
+    plan_mode_safe=True,
+    read_only=True,
+)

pcli/tools/registry.py

@@ -0,0 +1,138 @@
+"""Name -> ToolSpec lookup, and the OpenAI `tools=[...]` payload builder."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from pcli.llm.models import ToolDefinition
+from pcli.tools.base import ToolSpec
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolSpec] = {}
+
+    def register(self, tool: ToolSpec) -> None:
+        self._tools[tool.name] = tool
+
+    def merge(self, other: ToolRegistry) -> None:
+        for tool in other:
+            self.register(tool)
+
+    def filtered(self, predicate: Callable[[ToolSpec], bool]) -> ToolRegistry:
+        """A new registry containing only the tools predicate(tool) accepts —
+        the shared subsetting primitive behind spawn_subagent's allowed_tools,
+        plan mode's tool filtering, and agent tools' fixed allowed-tool sets."""
+        subset = ToolRegistry()
+        for tool in self:
+            if predicate(tool):
+                subset.register(tool)
+        return subset
+
+    def get(self, name: str) -> ToolSpec | None:
+        return self._tools.get(name)
+
+    def to_openai_tools(self) -> list[ToolDefinition]:
+        return [tool.to_openai_tool() for tool in self._tools.values()]
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._tools
+
+    def __iter__(self):
+        return iter(self._tools.values())
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+
+def build_default_registry() -> ToolRegistry:
+    from pcli.tools.agent_tools import (
+        DATA_ANALYSIS,
+        DEEP_RESEARCH,
+        EXPLORE_CODEBASE,
+        EXPLORE_FILES,
+        EXPLORE_LOGS,
+        VERIFY_COMPUTATION,
+        WRITE_DOCUMENTATION,
+    )
+    from pcli.tools.builtin.agent_tool_register_tool import REGISTER_AGENT_TOOL
+    from pcli.tools.builtin.artifact_tool import ASK_ARTIFACT, FETCH_ARTIFACT
+    from pcli.tools.builtin.ask_tool import ASK_USER_QUESTION
+    from pcli.tools.builtin.browser_tool import (
+        BROWSER_CLICK,
+        BROWSER_NAVIGATE,
+        BROWSER_PRESS_KEY,
+        BROWSER_READ_PAGE,
+        BROWSER_SCREENSHOT,
+        BROWSER_TYPE,
+        BROWSER_WAIT_FOR,
+    )
+    from pcli.tools.builtin.decision_tool import RECORD_DECISION
+    from pcli.tools.builtin.describe_tool import DESCRIBE_TOOL
+    from pcli.tools.builtin.diff_tools import APPLY_PATCH, DIFF_FILES
+    from pcli.tools.builtin.fs_tools import EDIT_FILE, GLOB_SEARCH, LIST_DIR, READ_FILE, WRITE_FILE
+    from pcli.tools.builtin.grep_tool import GREP
+    from pcli.tools.builtin.memory_tool import REMEMBER
+    from pcli.tools.builtin.network_tools import DOWNLOAD_FILE
+    from pcli.tools.builtin.pip_tool import PIP_INSTALL
+    from pcli.tools.builtin.shell_tool import (
+        READ_BACKGROUND_OUTPUT,
+        RUN_SHELL,
+        RUN_SHELL_BACKGROUND,
+        STOP_BACKGROUND_PROCESS,
+    )
+    from pcli.tools.builtin.subagent_tool import SPAWN_SUBAGENT
+    from pcli.tools.builtin.todo_tool import WRITE_TODOS
+    from pcli.tools.builtin.toolbox_register_tool import REGISTER_TOOLBOX_TOOL
+    from pcli.tools.builtin.web_tools import WEB_FETCH, WEB_SEARCH
+    from pcli.tools.pydiscovery.invoke import CALL_PYTHON
+    from pcli.tools.pydiscovery.search import INSPECT_PYTHON_MODULE, SEARCH_PYTHON
+
+    registry = ToolRegistry()
+    for tool in (
+        READ_FILE,
+        WRITE_FILE,
+        EDIT_FILE,
+        LIST_DIR,
+        GLOB_SEARCH,
+        GREP,
+        DOWNLOAD_FILE,
+        WEB_FETCH,
+        WEB_SEARCH,
+        DIFF_FILES,
+        APPLY_PATCH,
+        RUN_SHELL,
+        RUN_SHELL_BACKGROUND,
+        READ_BACKGROUND_OUTPUT,
+        STOP_BACKGROUND_PROCESS,
+        PIP_INSTALL,
+        SEARCH_PYTHON,
+        INSPECT_PYTHON_MODULE,
+        CALL_PYTHON,
+        SPAWN_SUBAGENT,
+        ASK_USER_QUESTION,
+        WRITE_TODOS,
+        RECORD_DECISION,
+        REMEMBER,
+        FETCH_ARTIFACT,
+        ASK_ARTIFACT,
+        REGISTER_TOOLBOX_TOOL,
+        EXPLORE_CODEBASE,
+        EXPLORE_FILES,
+        EXPLORE_LOGS,
+        WRITE_DOCUMENTATION,
+        VERIFY_COMPUTATION,
+        DEEP_RESEARCH,
+        DATA_ANALYSIS,
+        REGISTER_AGENT_TOOL,
+        BROWSER_NAVIGATE,
+        BROWSER_CLICK,
+        BROWSER_TYPE,
+        BROWSER_PRESS_KEY,
+        BROWSER_WAIT_FOR,
+        BROWSER_READ_PAGE,
+        BROWSER_SCREENSHOT,
+        DESCRIBE_TOOL,
+    ):
+        registry.register(tool)
+    return registry

pcli/tools/toolbox/introspect.py

@@ -0,0 +1,48 @@
+"""Generic `--help` walker for software without a curated plugin. Best-effort
+text corpus collection that feeds into synthesize.py — not a man-page/argparse
+parser, just enough structure-guessing to find likely subcommands."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pcli.sandbox.base import ExecRequest
+from pcli.sandbox.subprocess_backend import RestrictedSubprocessSandbox
+
+_SUBCOMMAND_RE = re.compile(r"^\s{2,4}([a-z][a-z0-9_-]{1,30})\s{2,}\S", re.MULTILINE)
+_MAX_SUBCOMMANDS = 8
+
+
+async def _run_help(invocation: list[str], args: list[str], cwd: Path) -> str:
+    sandbox = RestrictedSubprocessSandbox(allowed_roots=[cwd])
+    result = await sandbox.execute(
+        ExecRequest(command=[*invocation, *args], cwd=cwd, timeout_s=10)
+    )
+    return (result.stdout + "\n" + result.stderr).strip()
+
+
+def _guess_subcommands(help_text: str) -> list[str]:
+    seen: list[str] = []
+    for match in _SUBCOMMAND_RE.finditer(help_text):
+        word = match.group(1)
+        if word not in seen:
+            seen.append(word)
+    return seen[:_MAX_SUBCOMMANDS]
+
+
+async def collect_help_corpus(invocation: list[str], cwd: Path) -> str:
+    """invocation is the argv prefix used to run the target — [binary_path]
+    for a plain executable on PATH, or [sys.executable, script_path] for a
+    self-authored .py script that needs an interpreter (see
+    ToolboxManager.discover's path= parameter)."""
+    label = " ".join(invocation)
+    top_help = await _run_help(invocation, ["--help"], cwd)
+    parts = [f"$ {label} --help\n{top_help}"]
+
+    for subcommand in _guess_subcommands(top_help):
+        sub_help = await _run_help(invocation, [subcommand, "--help"], cwd)
+        if sub_help:
+            parts.append(f"$ {label} {subcommand} --help\n{sub_help}")
+
+    return "\n\n".join(parts)

pcli/tools/toolbox/manager.py

@@ -0,0 +1,336 @@
+"""ToolboxManager: user-triggered discovery of OS/software tools, persisted
+across sessions and merged into the shared ToolRegistry on every startup.
+
+Discovery is only ever invoked by discover() — nothing here runs
+automatically or in the background."""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+from pcli.llm.client import GatewayClient
+from pcli.sandbox.base import ExecRequest, SandboxSecurityError
+from pcli.sandbox.subprocess_backend import RestrictedSubprocessSandbox
+from pcli.tools.base import ToolContext, ToolResult, ToolSpec
+from pcli.tools.registry import ToolRegistry
+from pcli.tools.toolbox import store
+from pcli.tools.toolbox.introspect import collect_help_corpus
+from pcli.tools.toolbox.plugin_base import CommandSpec, DetectionResult, ToolboxPlugin
+from pcli.tools.toolbox.plugins import ALL_PLUGINS
+from pcli.tools.toolbox.synthesize import synthesize_tools
+
+
+class ToolboxDiscoveryError(Exception):
+    pass
+
+
+def _plugin_for(software_name: str) -> ToolboxPlugin | None:
+    for plugin in ALL_PLUGINS:
+        if plugin.software_name == software_name:
+            return plugin
+    return None
+
+
+async def _detect_primary_binary(
+    candidates: tuple[str, ...], version_args: tuple[str, ...], cwd: Path
+) -> tuple[str, str] | None:
+    for candidate in candidates:
+        binary_path = shutil.which(candidate)
+        if not binary_path:
+            continue
+        sandbox = RestrictedSubprocessSandbox(allowed_roots=[cwd])
+        result = await sandbox.execute(
+            ExecRequest(command=[binary_path, *version_args], cwd=cwd, timeout_s=10)
+        )
+        output = (result.stdout + "\n" + result.stderr).strip()
+        return binary_path, output
+    return None
+
+
+def make_command_tool_spec(software_name: str, spec: CommandSpec) -> ToolSpec:
+    tool_name = f"{software_name}_{spec.name}"
+
+    async def _handler(arguments: dict, ctx: ToolContext) -> ToolResult:
+        argv = [spec.binary_path, *spec.build_args(arguments)]
+        result = await ctx.sandbox.execute(ExecRequest(command=argv, cwd=ctx.cwd, timeout_s=30))
+        output = result.stdout
+        if result.stderr:
+            output += f"\n--- stderr ---\n{result.stderr}"
+        is_error = result.exit_code != 0 or result.timed_out
+        return ToolResult(output=f"[exit_code={result.exit_code}]\n{output}", is_error=is_error)
+
+    return ToolSpec(
+        name=tool_name,
+        description=spec.description,
+        parameters=spec.parameters,
+        handler=_handler,
+        needs_permission=spec.risk != "read",
+        needs_sandbox=True,
+        risk_description=f"Runs `{spec.binary_path}` ({spec.risk}).",
+        read_only=spec.risk == "read",
+    )
+
+
+def _auto_flags(arguments: dict, parameters: dict) -> list[str]:
+    """Generic best-effort flag builder for LLM-synthesized tools: each
+    provided argument becomes `--arg-name value` (or a bare flag for
+    booleans). Curated plugins use hand-written build_args instead because
+    real CLIs (positional args, short flags, `=` syntax) don't uniformly fit
+    this convention — this is the fallback for tools nobody's hand-reviewed."""
+    props = parameters.get("properties", {})
+    argv: list[str] = []
+    for key, value in arguments.items():
+        if value is None:
+            continue
+        flag = "--" + key.replace("_", "-")
+        prop_type = (props.get(key) or {}).get("type")
+        if prop_type == "boolean":
+            if value:
+                argv.append(flag)
+            continue
+        if isinstance(value, list):
+            for item in value:
+                argv += [flag, str(item)]
+            continue
+        argv += [flag, str(value)]
+    return argv
+
+
+def _invocation_for_path(path: Path) -> list[str]:
+    """.py scripts need an interpreter — Windows can't execve them directly,
+    and POSIX only can if they're chmod +x with a shebang, which a
+    self-authored script can't be relied on to have."""
+    if path.suffix.lower() == ".py":
+        return [sys.executable, str(path)]
+    return [str(path)]
+
+
+def make_synthesized_tool_spec(software_name: str, invocation: list[str], tool_data: dict) -> ToolSpec:
+    tool_name = f"{software_name}_{tool_data['name']}"
+    subcommand: list[str] = tool_data["subcommand"]
+    parameters: dict = tool_data["parameters"]
+    risk: str = tool_data.get("risk", "mutate")
+
+    async def _handler(arguments: dict, ctx: ToolContext) -> ToolResult:
+        argv = [*invocation, *subcommand, *_auto_flags(arguments, parameters)]
+        result = await ctx.sandbox.execute(ExecRequest(command=argv, cwd=ctx.cwd, timeout_s=30))
+        output = result.stdout
+        if result.stderr:
+            output += f"\n--- stderr ---\n{result.stderr}"
+        is_error = result.exit_code != 0 or result.timed_out
+        return ToolResult(output=f"[exit_code={result.exit_code}]\n{output}", is_error=is_error)
+
+    invocation_label = " ".join(invocation)
+    return ToolSpec(
+        name=tool_name,
+        description=tool_data["description"]
+        + " (auto-generated from --help output; unreviewed, verify before trusting blindly)",
+        parameters=parameters,
+        handler=_handler,
+        needs_permission=risk != "read",
+        needs_sandbox=True,
+        risk_description=f"Runs `{invocation_label} {' '.join(subcommand)}` ({risk}, auto-generated).",
+        read_only=risk == "read",
+    )
+
+
+class ToolboxManager:
+    def __init__(self, *, cwd: Path) -> None:
+        self._cwd = cwd
+
+    def _resolve_script_path(self, path: str) -> Path:
+        """Resolves+validates a self-authored script for discover's path=
+        parameter: must land inside self._cwd (the same containment
+        RestrictedSubprocessSandbox._validate_cwd enforces for every other
+        tool), so a path argument can't reach outside the project tree the
+        agent is actually working in."""
+        candidate = Path(path).expanduser()
+        if not candidate.is_absolute():
+            candidate = self._cwd / candidate
+        resolved = candidate.resolve()
+        cwd_resolved = self._cwd.expanduser().resolve()
+        if resolved != cwd_resolved and cwd_resolved not in resolved.parents:
+            raise SandboxSecurityError(
+                f"'{path}' is outside the working directory '{cwd_resolved}'."
+            )
+        if not resolved.is_file():
+            raise ToolboxDiscoveryError(f"'{path}' doesn't exist or isn't a file.")
+        return resolved
+
+    async def discover(
+        self,
+        software_name: str,
+        *,
+        gateway_client: GatewayClient | None = None,
+        model: str | None = None,
+        path: str | None = None,
+    ) -> str:
+        """path registers a self-authored script directly, bypassing PATH
+        lookup entirely — for a model that just wrote its own small tool and
+        wants to make it callable without the user placing it on PATH first.
+        Curated-plugin matching is skipped when path is given: pointing at a
+        specific script means "use exactly this," not "look something up.\""""
+        registry = store.read_registry()
+
+        if path is not None:
+            script_path = self._resolve_script_path(path)
+            invocation = _invocation_for_path(script_path)
+            help_corpus = await collect_help_corpus(invocation, self._cwd)
+            if not help_corpus.strip():
+                raise ToolboxDiscoveryError(
+                    f"'{' '.join(invocation)} --help' produced no output to work from."
+                )
+            corpus_hash = store.hash_corpus(help_corpus)
+
+            cached = store.read_synthesized_schema(software_name)
+            if cached and cached.get("help_corpus_hash") == corpus_hash:
+                tools_data = cached["tools"]
+            else:
+                if gateway_client is None:
+                    raise ToolboxDiscoveryError(
+                        f"No LLM gateway configured to synthesize a tool schema for "
+                        f"'{software_name}'."
+                    )
+                tools_data = await synthesize_tools(
+                    gateway_client, software_name=software_name, help_corpus=help_corpus, model=model
+                )
+                store.write_synthesized_schema(
+                    software_name, help_corpus_hash=corpus_hash, version="unknown", tools=tools_data
+                )
+
+            registry[software_name] = {
+                "source": "synthesized",
+                "binary_path": str(script_path),
+                "invocation": invocation,
+                "version": "unknown",
+                "tool_count": len(tools_data),
+            }
+            store.write_registry(registry)
+            return (
+                f"Registered '{software_name}' from {script_path} — synthesized "
+                f"{len(tools_data)} tool(s) from --help output."
+            )
+
+        plugin = _plugin_for(software_name)
+
+        if plugin is not None:
+            found = await _detect_primary_binary(plugin.binary_names, plugin.version_args, self._cwd)
+            if found is None:
+                raise ToolboxDiscoveryError(
+                    f"Could not find '{software_name}' on PATH "
+                    f"(tried: {', '.join(plugin.binary_names)})."
+                )
+            binary_path, version_output = found
+            version = plugin.parse_version(version_output) or (0,)
+            first_line = version_output.strip().splitlines()[0] if version_output.strip() else "unknown"
+            detection = DetectionResult(
+                software_name=software_name,
+                binary_path=binary_path,
+                version_string=first_line,
+                version=version,
+            )
+            tools = plugin.build_tools(detection)
+            registry[software_name] = {
+                "source": "curated",
+                "binary_path": binary_path,
+                "version": detection.version_string,
+                "tool_count": len(tools),
+            }
+            store.write_registry(registry)
+            return (
+                f"Found curated plugin for '{software_name}' at {binary_path} "
+                f"(version: {detection.version_string}). Registered {len(tools)} tool(s)."
+            )
+
+        binary_path = shutil.which(software_name)
+        if not binary_path:
+            raise ToolboxDiscoveryError(f"'{software_name}' was not found on PATH.")
+
+        help_corpus = await collect_help_corpus([binary_path], self._cwd)
+        if not help_corpus.strip():
+            raise ToolboxDiscoveryError(f"'{software_name} --help' produced no output to work from.")
+        corpus_hash = store.hash_corpus(help_corpus)
+
+        cached = store.read_synthesized_schema(software_name)
+        if cached and cached.get("help_corpus_hash") == corpus_hash:
+            tools_data = cached["tools"]
+        else:
+            if gateway_client is None:
+                raise ToolboxDiscoveryError(
+                    f"No curated plugin for '{software_name}' and no LLM gateway configured "
+                    "to synthesize one."
+                )
+            tools_data = await synthesize_tools(
+                gateway_client, software_name=software_name, help_corpus=help_corpus, model=model
+            )
+            store.write_synthesized_schema(
+                software_name, help_corpus_hash=corpus_hash, version="unknown", tools=tools_data
+            )
+
+        registry[software_name] = {
+            "source": "synthesized",
+            "binary_path": binary_path,
+            "invocation": [binary_path],
+            "version": "unknown",
+            "tool_count": len(tools_data),
+        }
+        store.write_registry(registry)
+        return (
+            f"No curated plugin for '{software_name}' — introspected {binary_path} and "
+            f"synthesized {len(tools_data)} tool(s) from --help output."
+        )
+
+    def list_discovered(self) -> dict[str, dict]:
+        return store.read_registry()
+
+    def remove(self, software_name: str) -> None:
+        registry = store.read_registry()
+        registry.pop(software_name, None)
+        store.write_registry(registry)
+
+    async def load_all(self) -> ToolRegistry:
+        """Rebuilds tool specs for every previously-discovered software.
+        Curated entries re-detect live (cheap); synthesized entries load
+        their cached schema. Missing binaries are skipped silently rather
+        than raising, so a stale registry entry doesn't break startup."""
+        registry = ToolRegistry()
+
+        for software_name, entry in store.read_registry().items():
+            plugin = _plugin_for(software_name)
+            if plugin is not None:
+                found = await _detect_primary_binary(plugin.binary_names, plugin.version_args, self._cwd)
+                if found is None:
+                    continue
+                binary_path, version_output = found
+                version = plugin.parse_version(version_output) or (0,)
+                first_line = (
+                    version_output.strip().splitlines()[0] if version_output.strip() else "unknown"
+                )
+                detection = DetectionResult(
+                    software_name=software_name,
+                    binary_path=binary_path,
+                    version_string=first_line,
+                    version=version,
+                )
+                for spec in plugin.build_tools(detection):
+                    registry.register(make_command_tool_spec(software_name, spec))
+            else:
+                cached = store.read_synthesized_schema(software_name)
+                if cached is None:
+                    continue
+                invocation = entry.get("invocation")
+                if not invocation:
+                    # Registry entries written before the invocation field
+                    # existed only have binary_path - fall back to it.
+                    binary_path = entry.get("binary_path") or shutil.which(software_name)
+                    if not binary_path:
+                        continue
+                    invocation = [binary_path]
+                for tool_data in cached["tools"]:
+                    registry.register(
+                        make_synthesized_tool_spec(software_name, invocation, tool_data)
+                    )
+
+        return registry

pcli/tools/toolbox/plugin_base.py

@@ -0,0 +1,51 @@
+"""Plugin architecture for curated per-software tool sets.
+
+A plugin declares how to recognize its software (candidate binary names +
+how to run/parse a version check) and, once detected, the specific
+admin/ops/user commands it exposes as tools. Each CommandSpec carries its
+own already-resolved `binary_path` rather than assuming one binary for the
+whole plugin — most software (kubectl, apachectl) is one binary with many
+subcommands, but some (Sun Grid Engine: qstat/qsub/qdel/...) is a suite of
+separate binaries, and this shape covers both without special-casing.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+@dataclass
+class DetectionResult:
+    software_name: str
+    binary_path: str
+    """Path to the plugin's primary binary (used to confirm presence/version)."""
+    version_string: str
+    version: tuple[int, ...]
+
+
+@dataclass
+class CommandSpec:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    """JSON schema for the tool's arguments."""
+    build_args: Callable[[dict[str, Any]], list[str]]
+    """Given validated tool arguments, returns the argv (after the binary)."""
+    binary_path: str
+    risk: Literal["read", "mutate", "destructive"] = "read"
+
+
+class ToolboxPlugin(ABC):
+    software_name: str
+    binary_names: tuple[str, ...]
+    """Candidate primary-binary names to look for on PATH, tried in order."""
+    version_args: tuple[str, ...] = ("--version",)
+
+    @abstractmethod
+    def parse_version(self, version_output: str) -> tuple[int, ...] | None: ...
+
+    @abstractmethod
+    def build_tools(self, detection: DetectionResult) -> list[CommandSpec]: ...