pcli-agent 0.1.0__py3-none-any.whl

pcli/tools/agent_tools_store.py

@@ -0,0 +1,69 @@
+"""Persistence for user/model-registered agent tools (see
+tools/agent_tools.py's make_agent_tool and
+tools/builtin/agent_tool_register_tool.py), mirroring tools/toolbox/store.py's
+shape but keyed by tool name rather than software name."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from pcli.config.paths import agent_tools_file
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    tmp_path.write_text(content, encoding="utf-8")
+    os.replace(tmp_path, path)
+
+
+def read_agent_tools() -> dict[str, dict]:
+    path = agent_tools_file()
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_agent_tools(agent_tools: dict[str, dict]) -> None:
+    _atomic_write(agent_tools_file(), json.dumps(agent_tools, indent=2))
+
+
+def save_agent_tool(
+    name: str,
+    *,
+    description: str,
+    persona_prompt: str,
+    allowed_tools: list[str],
+    plan_mode_safe: bool,
+) -> None:
+    agent_tools = read_agent_tools()
+    agent_tools[name] = {
+        "description": description,
+        "persona_prompt": persona_prompt,
+        "allowed_tools": allowed_tools,
+        "plan_mode_safe": plan_mode_safe,
+    }
+    write_agent_tools(agent_tools)
+
+
+def load_persisted_agent_tools():
+    """Builds a ToolRegistry from every agent tool saved via save_agent_tool
+    — called once at startup (ChatScreen.on_mount) so they survive restarts,
+    same as toolbox tools."""
+    from pcli.tools.agent_tools import make_agent_tool
+    from pcli.tools.registry import ToolRegistry
+
+    registry = ToolRegistry()
+    for name, spec in read_agent_tools().items():
+        registry.register(
+            make_agent_tool(
+                name=name,
+                description=spec["description"],
+                persona_prompt=spec["persona_prompt"],
+                allowed_tool_names=spec["allowed_tools"],
+                plan_mode_safe=spec.get("plan_mode_safe", False),
+            )
+        )
+    return registry

pcli/tools/artifacts.py

@@ -0,0 +1,47 @@
+"""The 'artifact library': large tool outputs get truncated out of the live
+conversation (see AgentLoop's dispatch) and archived here instead, so they
+don't get re-sent to the model on every subsequent call. The LLM can pull
+one back with the fetch_artifact tool when it actually needs the detail.
+
+Backed by the session's own blob storage rather than a separate mechanism,
+so archived content persists/exports/imports exactly like everything else
+in the session — an artifact_id doubles as a ToolInvocation.full_result_ref.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from pcli.session.store import SessionStore
+from pcli.util.ids import new_id
+
+
+class ArtifactStore(Protocol):
+    def put(self, content: str) -> str:
+        """Archives content, returning a stable artifact_id to retrieve it by."""
+        ...
+
+    def get(self, artifact_id: str) -> str | None:
+        """Returns the archived content, or None if artifact_id is unknown."""
+        ...
+
+
+class SessionArtifactStore:
+    def __init__(self, store: SessionStore, session_id: str) -> None:
+        self._store = store
+        self._session_id = session_id
+
+    def put(self, content: str) -> str:
+        artifact_id = new_id("art_")
+        self._store.write_blob_named(self._session_id, self.blob_name_for(artifact_id), content)
+        return artifact_id
+
+    def get(self, artifact_id: str) -> str | None:
+        try:
+            return self._store.read_blob(self._session_id, self.blob_name_for(artifact_id))
+        except FileNotFoundError:
+            return None
+
+    @staticmethod
+    def blob_name_for(artifact_id: str) -> str:
+        return f"{artifact_id}.txt"

pcli/tools/base.py

@@ -0,0 +1,185 @@
+"""Tool definitions: what the LLM can call, and how a call actually runs."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from pcli.agent.activity import ActivityTracker
+from pcli.llm.client import GatewayClient
+from pcli.llm.models import ToolDefinition, Usage
+from pcli.permissions.guardrails import GuardrailsConfig
+from pcli.permissions.manager import AskCallback, PermissionManager
+from pcli.sandbox.base import Sandbox
+from pcli.session.models import Session
+from pcli.tools.artifacts import ArtifactStore
+
+if TYPE_CHECKING:
+    from pcli.browser.session import BrowserSession
+    from pcli.tools.registry import ToolRegistry
+    from pcli.tools.toolbox.manager import ToolboxManager
+
+
+AskQuestionCallback = Callable[[str, list[str] | None], Awaitable[str]]
+
+
+@dataclass
+class ToolContext:
+    sandbox: Sandbox
+    guardrails: GuardrailsConfig
+    cwd: Path
+    # The rest are only populated for the top-level agent loop's context; most
+    # tool handlers never touch them. They exist so a tool (namely
+    # spawn_subagent) can construct its own nested AgentLoop that shares the
+    # parent's gateway/tools/permissions instead of re-plumbing all of this
+    # through a parallel context type.
+    gateway_client: GatewayClient | None = None
+    model: str | None = None
+    tool_registry: ToolRegistry | None = None
+    permission_manager: PermissionManager | None = None
+    ask: AskCallback | None = None
+    ask_question: AskQuestionCallback | None = None
+    """Callback for ask_user_question (tools/builtin/ask_tool.py) to pause a
+    turn and ask the user something directly - see AskQuestionModal. Kept
+    separate from `ask` (permission decisions only, a fixed allow/deny/
+    remember-scope shape) since this is a free-form question/answer, not a
+    permission choice."""
+    max_tool_iterations: int | None = 25
+    """None means unlimited (local-api mode)."""
+    subagent_max_iterations: int = 30
+    """Hard ceiling on a nested subagent's own tool-call iterations (see
+    Settings.subagent_max_iterations) - unlike max_tool_iterations above,
+    this is never None/unlimited, even in local-api mode."""
+    max_response_tokens: int | None = None
+    """The parent AgentLoop's current dynamic max_tokens cap (cost/context.py's
+    compute_max_response_tokens), threaded through so a nested AgentLoop
+    (spawn_subagent, agent_tools.py's make_agent_tool) inherits it instead of
+    running with no cap at all — see AgentLoop.max_response_tokens."""
+    temperature: float | None = None
+    """The parent AgentLoop's current sampling temperature (Settings.
+    default_temperature via /temperature), threaded through for the same
+    subagent-inheritance reason as max_response_tokens above."""
+    subagent_depth: int = 0
+    session: Session | None = None
+    """The live Session object, for tools that read/mutate session-level state
+    directly (namely write_todos)."""
+    max_session_cost_usd: float | None = None
+    """Settings.max_session_cost_usd, threaded through so a nested AgentLoop
+    (spawn_subagent, memory extraction) can build the same cost/tracker.py
+    cost_budget_reason(session, max_session_cost_usd) check the parent loop
+    uses, instead of a subagent blowing straight through the session's
+    budget while the parent's own check is paused waiting for it to
+    return."""
+    artifact_store: ArtifactStore | None = None
+    """Where large tool outputs get archived (see agent/loop.py's automatic
+    truncation) and where fetch_artifact reads them back from."""
+    activity: ActivityTracker | None = None
+    """Ephemeral live-progress reporting for the TUI's status pane (namely
+    spawn_subagent reporting its own tool-call progress). Not persisted."""
+    toolbox_manager: ToolboxManager | None = None
+    """Lets register_toolbox_tool trigger toolbox discovery directly,
+    mirroring what the /toolbox discover slash command does."""
+    plan_mode: bool = False
+    """True while the session is in plan mode — checked by AgentLoop as a
+    dispatch-time backstop (see _dispatch_tool_call) independent of whatever
+    registry the caller happened to build, and by spawn_subagent to keep a
+    nested subagent from being used as a plan-mode bypass."""
+    brave_search_api_key: str = ""
+    """web_search (tools/builtin/web_tools.py) uses this real, supported API
+    when configured (non-empty); otherwise it falls back to a best-effort,
+    no-API-key scrape of DuckDuckGo's HTML results page."""
+    memory_enabled: bool = True
+    """Settings.memory_enabled, threaded through so remember
+    (tools/builtin/memory_tool.py) and _nested_agent.py's subagent-prompt
+    memory injection don't need to reach for get_settings() themselves."""
+    memory_max_entries: int = 40
+    """Settings.memory_max_entries - the cap remember's add_entry() enforces
+    (memory/store.py)."""
+    browser_session: BrowserSession | None = None
+    """Shared Playwright wrapper for the browser_* tools (tools/builtin/
+    browser_tool.py) - one instance per AgentRuntime (agent/runtime.py),
+    threaded through unchanged so every call in a session reuses the same
+    browser tab/login state. None only for a caller that never set up an
+    AgentRuntime at all (e.g. a bare ToolContext built directly in a test)."""
+
+
+@dataclass
+class ToolResult:
+    output: str
+    is_error: bool = False
+    extra_usage: list[Usage] = field(default_factory=list)
+    """LLM usage incurred by the tool call itself (e.g. a subagent's own LLM
+    calls) that didn't come from the turn's main chat_stream — the caller
+    folds this into cost tracking so subagent spend isn't silently dropped."""
+
+
+ToolHandler = Callable[[dict[str, Any], ToolContext], Awaitable[ToolResult]]
+
+
+@dataclass
+class ToolSpec:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    """JSON schema for the tool's arguments (the OpenAI-style `function.parameters`)."""
+    handler: ToolHandler
+    needs_permission: bool = True
+    needs_sandbox: bool = False
+    risk_description: str = ""
+    guardrail_command_arg: str | None = None
+    """Name of the argument holding a shell command, if any — checked against
+    the shell denylist regardless of needs_permission."""
+    guardrail_path_arg: str | None = None
+    """Name of the argument holding a filesystem path, if any — checked
+    against allowed_roots/deny_paths regardless of needs_permission."""
+    guardrail_python_module_arg: str | None = None
+    """Name of the argument holding a (possibly dotted) Python module/qualified
+    name, if any — its top-level module is checked against the module denylist
+    regardless of needs_permission."""
+    plan_mode_safe: bool = False
+    """Explicit opt-in for use while plan mode is active. Deliberately NOT
+    derived from needs_permission — needs_permission=False is not an accurate
+    read-only proxy (e.g. write_todos/record_decision mutate session state
+    but don't need permission)."""
+    read_only: bool = False
+    """The authoritative "does calling this tool, by itself, mutate
+    anything outside its own return value" flag (no filesystem/shell/
+    session/memory/registry/browser-state changes) - used by `pcli tools
+    list`. Deliberately its own field, not derived from needs_permission or
+    plan_mode_safe: neither is an accurate read-only proxy either (see
+    plan_mode_safe's own docstring above for the needs_permission case;
+    plan_mode_safe=True doesn't imply read-only either - spawn_subagent and
+    deep_research are both plan_mode_safe=True but can run arbitrary
+    allowed-tool effects, including run_shell, outside of plan mode)."""
+
+    def to_openai_tool(self) -> ToolDefinition:
+        """The advertised schema gets an extra, optional "purpose" property
+        injected on top of self.parameters — a shallow copy, never mutating
+        self.parameters itself, which stays the schema AgentLoop validates
+        real arguments against (see _dispatch_tool_call, which pops
+        "purpose" out before that validation and before the tool handler
+        ever sees it — this property exists purely for the model's benefit,
+        not as a real tool argument)."""
+        parameters = self.parameters
+        if "properties" in parameters:
+            parameters = {
+                **parameters,
+                "properties": {
+                    **parameters["properties"],
+                    "purpose": {
+                        "type": "string",
+                        "description": "Optional: a short, one-sentence reason you're calling "
+                        "this tool right now (e.g. 'checking whether pdftotext is installed'). "
+                        "Helps keep tool-call history readable and prunable.",
+                    },
+                },
+            }
+        return ToolDefinition(
+            function={
+                "name": self.name,
+                "description": self.description,
+                "parameters": parameters,
+            }
+        )

pcli/tools/builtin/agent_tool_register_tool.py

@@ -0,0 +1,100 @@
+"""register_agent_tool: lets the LLM define a new named subagent persona,
+restricted to a fixed set of already-existing tools, callable afterward as
+a single tool with one 'query' argument — the same underlying mechanism as
+spawn_subagent (tools/agent_tools.py's make_agent_tool), but with the
+persona/allowed-tools baked in at registration time instead of supplied by
+the calling model on every call. Persisted (tools/agent_tools_store.py) so
+it survives restarts, mirroring register_toolbox_tool but for subagent
+personas instead of external scripts.
+"""
+
+from __future__ import annotations
+
+from pcli.tools.agent_tools import make_agent_tool
+from pcli.tools.agent_tools_store import save_agent_tool
+from pcli.tools.base import ToolContext, ToolResult, ToolSpec
+
+
+async def _register_agent_tool(arguments: dict, ctx: ToolContext) -> ToolResult:
+    if ctx.tool_registry is None:
+        return ToolResult(output="Agent tools aren't available in this context.", is_error=True)
+
+    name = arguments["name"]
+    description = arguments["description"]
+    persona_prompt = arguments["persona_prompt"]
+    allowed_tools = arguments["allowed_tools"]
+    plan_mode_safe = arguments.get("plan_mode_safe", False)
+
+    unknown = [t for t in allowed_tools if t not in ctx.tool_registry]
+    if unknown:
+        return ToolResult(
+            output=f"Unknown tool name(s): {', '.join(unknown)}\n"
+            "[pcli] Suggestion: only reference tools that already exist in your own tool set "
+            "(check the exact names you were given).",
+            is_error=True,
+        )
+
+    save_agent_tool(
+        name,
+        description=description,
+        persona_prompt=persona_prompt,
+        allowed_tools=allowed_tools,
+        plan_mode_safe=plan_mode_safe,
+    )
+    tool = make_agent_tool(
+        name=name,
+        description=description,
+        persona_prompt=persona_prompt,
+        allowed_tool_names=allowed_tools,
+        plan_mode_safe=plan_mode_safe,
+    )
+    ctx.tool_registry.register(tool)
+
+    return ToolResult(output=f"Registered agent tool '{name}' — callable from now on.")
+
+
+REGISTER_AGENT_TOOL = ToolSpec(
+    name="register_agent_tool",
+    description="Defines a new named subagent persona, callable afterward as a single tool "
+    "with one 'query' argument. Use this when you find yourself wanting to delegate the same "
+    "kind of focused sub-task repeatedly (a consistent persona and a fixed, restricted set of "
+    "tools), rather than repeatedly spelling out the same instructions to spawn_subagent. "
+    "Persists across restarts — this is a judgment call for genuinely repetitive delegation, "
+    "not every one-off task.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "name": {
+                "type": "string",
+                "description": "Tool name the model will call it by afterward.",
+            },
+            "description": {
+                "type": "string",
+                "description": "Shown to the calling model as this tool's description.",
+            },
+            "persona_prompt": {
+                "type": "string",
+                "description": "System prompt for the nested subagent: its role/persona and "
+                "how it should approach its task.",
+            },
+            "allowed_tools": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Fixed set of existing tool names the nested subagent is "
+                "restricted to.",
+            },
+            "plan_mode_safe": {
+                "type": "boolean",
+                "description": "Whether this new tool should stay usable while plan mode is "
+                "active (default false). Only set true if every tool in allowed_tools is "
+                "itself read-only/exploration-only.",
+            },
+        },
+        "required": ["name", "description", "persona_prompt", "allowed_tools"],
+    },
+    handler=_register_agent_tool,
+    needs_permission=True,
+    risk_description="Registers a new tool the model can call in later turns — grants standing "
+    "execution rights to a nested subagent, a bigger action than running one command.",
+    read_only=False,
+)

pcli/tools/builtin/artifact_tool.py

@@ -0,0 +1,212 @@
+"""fetch_artifact: retrieves the full (or a windowed slice of the) content of
+a large tool result that AgentLoop truncated out of the live conversation
+and archived — see pcli.tools.artifacts and agent/loop.py's dispatch logic.
+
+ask_artifact (this module too - same domain, one small addition) answers a
+specific question about an archived artifact via a side LLM call instead of
+returning raw content, so a small-context model doesn't have to pull the
+whole thing into its own conversation just to do its own reading
+comprehension over it. Local-api-only (see tui/screens/chat.py, which
+excludes it from the tool registry otherwise): the extra call is free on a
+local gateway, real (if usually small) cost on a paid one."""
+
+from __future__ import annotations
+
+import re
+
+from pcli.llm.models import ChatMessage
+from pcli.tools.base import ToolContext, ToolResult, ToolSpec
+
+_DEFAULT_FETCH_CHARS = 4000
+_MAX_PATTERN_MATCHES = 50
+_DEFAULT_CONTEXT_LINES = 2
+
+_ASK_ARTIFACT_SYSTEM_PROMPT = (
+    "Answer the question using only the reference material below. Be concise and direct. If "
+    "the material doesn't contain the answer, say so plainly rather than guessing."
+)
+
+
+def _artifact_not_found(artifact_id: str) -> ToolResult:
+    return ToolResult(
+        output=f"No artifact found with id '{artifact_id}'.\n"
+        "[pcli] Suggestion: re-check the \"archived as artifact_id='art_...'\" note in the "
+        "original tool result rather than guessing an id — artifact ids aren't derivable "
+        "any other way.",
+        is_error=True,
+    )
+
+
+def _grep_with_context(
+    content: str, pattern: str, context_lines: int, max_chars: int
+) -> tuple[str, int]:
+    """Grep-style search within an already-fetched artifact: finds every
+    line matching `pattern`, keeps context_lines of surrounding lines per
+    match (like grep -C), and merges overlapping/adjacent windows so
+    nearby matches don't duplicate shared lines. Returns (rendered text,
+    total match count) — the caller reports the count separately since it
+    may exceed what's actually rendered (capped at _MAX_PATTERN_MATCHES
+    matches and max_chars of output)."""
+    lines = content.splitlines()
+    regex = re.compile(pattern)
+    match_indices = [i for i, line in enumerate(lines) if regex.search(line)]
+    total_matches = len(match_indices)
+
+    windows: list[tuple[int, int]] = []
+    for i in match_indices[:_MAX_PATTERN_MATCHES]:
+        start = max(0, i - context_lines)
+        end = min(len(lines) - 1, i + context_lines)
+        if windows and start <= windows[-1][1] + 1:
+            windows[-1] = (windows[-1][0], max(windows[-1][1], end))
+        else:
+            windows.append((start, end))
+
+    blocks = [
+        "\n".join(f"{idx + 1}: {lines[idx]}" for idx in range(start, end + 1))
+        for start, end in windows
+    ]
+    text = "\n--\n".join(blocks)
+    if len(text) > max_chars:
+        text = text[:max_chars] + "\n[...output truncated to max_chars...]"
+    return text, total_matches
+
+
+async def _fetch_artifact(arguments: dict, ctx: ToolContext) -> ToolResult:
+    if ctx.artifact_store is None:
+        return ToolResult(output="No artifact store available in this context.", is_error=True)
+
+    artifact_id = arguments["artifact_id"]
+    content = ctx.artifact_store.get(artifact_id)
+    if content is None:
+        return _artifact_not_found(artifact_id)
+
+    limit = int(arguments.get("limit") or _DEFAULT_FETCH_CHARS)
+    pattern = arguments.get("pattern")
+
+    if pattern:
+        try:
+            re.compile(pattern)
+        except re.error as exc:
+            return ToolResult(
+                output=f"Invalid regex: {exc}\n"
+                "[pcli] Suggestion: if you don't need regex features, escape the special "
+                "character(s) or search for a plain substring instead.",
+                is_error=True,
+            )
+        context_lines = int(arguments.get("context_lines") or _DEFAULT_CONTEXT_LINES)
+        text, total_matches = _grep_with_context(content, pattern, context_lines, limit)
+        if total_matches == 0:
+            return ToolResult(output=f"No lines matching {pattern!r} found in this artifact.")
+        header = f"{total_matches} matching line(s)"
+        if total_matches > _MAX_PATTERN_MATCHES:
+            header += f" (showing first {_MAX_PATTERN_MATCHES})"
+        return ToolResult(output=f"{header}:\n{text}")
+
+    offset = max(0, int(arguments.get("offset") or 0))
+    total = len(content)
+    window = content[offset : offset + limit]
+    end = offset + len(window)
+    footer = ""
+    if end < total:
+        footer = f"\n\n[showing chars {offset}-{end} of {total} total; call again with offset={end} for more]"
+    return ToolResult(output=window + footer)
+
+
+FETCH_ARTIFACT = ToolSpec(
+    name="fetch_artifact",
+    description="Retrieve the full content of a large tool result that was truncated out of "
+    "the conversation and archived (you'll see a note like \"archived as "
+    "artifact_id='art_...'\" when this happens). Supports offset/limit to page through very "
+    "large artifacts without pulling the whole thing into context at once, or a grep-style "
+    "pattern to jump straight to the part you need.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "artifact_id": {"type": "string"},
+            "pattern": {
+                "type": "string",
+                "description": "Regex — if given, returns only matching lines plus "
+                "context_lines of surrounding context (like grep -C), instead of a raw "
+                "character slice. Prefer this over offset/limit when you know what you're "
+                "looking for — offset is ignored when pattern is given.",
+            },
+            "context_lines": {
+                "type": "integer",
+                "description": "Lines of context before/after each match when pattern is "
+                "given (default 2).",
+            },
+            "offset": {
+                "type": "integer",
+                "description": "Character offset to start from (default 0). Ignored when "
+                "pattern is given.",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Max characters to return (default 4000). Also caps output "
+                "when pattern is given.",
+            },
+        },
+        "required": ["artifact_id"],
+    },
+    handler=_fetch_artifact,
+    needs_permission=False,
+    plan_mode_safe=True,
+    read_only=True,
+)
+
+
+async def _ask_artifact(arguments: dict, ctx: ToolContext) -> ToolResult:
+    if ctx.artifact_store is None:
+        return ToolResult(output="No artifact store available in this context.", is_error=True)
+    if ctx.gateway_client is None:
+        return ToolResult(output="No gateway available in this context.", is_error=True)
+
+    artifact_id = arguments["artifact_id"]
+    question = arguments["question"]
+    content = ctx.artifact_store.get(artifact_id)
+    if content is None:
+        return _artifact_not_found(artifact_id)
+
+    if len(content) <= _DEFAULT_FETCH_CHARS:
+        # Already small enough that fetch_artifact would return it whole -
+        # spending an extra LLM call on it would just add latency (the
+        # money's free, the round trip isn't) for no benefit over reading
+        # it directly.
+        return ToolResult(
+            output=f"Artifact is small enough to return directly (no extra LLM call needed):"
+            f"\n\n{content}"
+        )
+
+    messages = [
+        ChatMessage(role="system", content=_ASK_ARTIFACT_SYSTEM_PROMPT),
+        ChatMessage(role="user", content=f"Question: {question}\n\nReference material:\n{content}"),
+    ]
+    assistant_message, usage = await ctx.gateway_client.collect(messages, model=ctx.model)
+    answer = assistant_message.content or "(no answer produced)"
+    return ToolResult(output=answer, extra_usage=[usage])
+
+
+ASK_ARTIFACT = ToolSpec(
+    name="ask_artifact",
+    description="Answer a specific question about a large archived artifact via a side LLM "
+    "call, instead of pulling its raw content into this conversation - only available with a "
+    "local gateway (the extra call is free there). Prefer this over fetch_artifact when you "
+    "want a targeted answer from a large artifact rather than the raw text itself (small "
+    "artifacts are returned directly with no extra call, same as fetch_artifact would).",
+    parameters={
+        "type": "object",
+        "properties": {
+            "artifact_id": {"type": "string"},
+            "question": {
+                "type": "string",
+                "description": "What you want to know from this artifact, stated as a "
+                "specific question.",
+            },
+        },
+        "required": ["artifact_id", "question"],
+    },
+    handler=_ask_artifact,
+    needs_permission=False,
+    plan_mode_safe=True,
+    read_only=True,
+)