pcli-agent 0.1.0__py3-none-any.whl

pcli/memory/extraction.py

@@ -0,0 +1,106 @@
+"""Autonomous memory extraction: after a compaction pass archives a chunk of
+old conversation away (agent/compaction.py's maybe_compact), review that
+transcript - plus what's already known - and classify anything worth
+noting into one of remember's two scopes (tools/builtin/memory_tool.py) -
+global (persisted, cross-session, cross-project) or local (not persisted
+at all - a correctly-labeled dead end for project-specific content, not a
+lesser fallback). Runs as a small, tool-only AgentLoop scoped to just that
+one tool - no sandbox, shell, or file access needed or wanted here, unlike
+a real subagent (tools/_nested_agent.py).
+
+The explicit local category exists because leaving this as an implicit
+binary "durable enough to remember, or not" judgment demonstrably failed in
+practice: a real derived entry once got filed under the global 'preference'
+category even though its content (a specific package's import error in one
+project's test script) was clearly project-specific, not durable. Giving
+the model a concrete, named place for "worth noting but not global" - the
+same kind of discrete choice it already makes among the four global
+categories - is the fix: classifying into a parallel category is a more
+reliable task for an LLM than making an abstract counterfactual judgment
+("would this matter in some hypothetical future project?") inline while
+also deciding whether to act at all.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from pcli.agent.loop import AgentLoop
+from pcli.cost.tracker import cost_budget_reason
+from pcli.llm.models import ChatMessage, Usage, UsageEvent
+from pcli.memory.models import render_memory_section
+from pcli.memory.store import read_memory
+from pcli.tools.base import ToolContext
+from pcli.tools.builtin.memory_tool import REMEMBER
+from pcli.tools.registry import ToolRegistry
+
+_EXTRACTION_SYSTEM_PROMPT = (
+    "You review a chunk of an in-progress coding-agent conversation and classify anything "
+    "worth noting into exactly one of two scopes. Be strict - most reviews should add zero "
+    "or one fact, not several.\n\n"
+    "GLOBAL - call remember(content, category) with category='profile' (their role or "
+    "domain), 'preference' (a recurring technical/workflow choice), 'style' (how they like "
+    "responses/conversation), or 'common_ask' (a task they repeatedly ask for across "
+    "different projects) ONLY for a fact that is true of the USER as a person, independent "
+    "of whatever project this conversation happens to be about. Before using one of these "
+    "four categories, check: would this sentence still make complete sense, with no "
+    "confusion, read cold at the start of a totally unrelated project with none of this "
+    "conversation's context? If no, it is not global - do not file it under one of these "
+    "four categories just because it seems important right now.\n\n"
+    "LOCAL - call remember(content, category='local') for anything that seems worth noting "
+    "but is specific to the current project, repo, file, or task: project/package names, "
+    "the specifics of a bug under investigation, a decision that only matters for this "
+    "codebase. This is the correct, intentional choice for most of what comes up in a "
+    "normal conversation - not a lesser fallback. Nothing saved this way is ever persisted "
+    "or shown again; it exists so you have somewhere correct to put project-specific "
+    "content instead of discarding it silently or stretching it to fit a global category.\n\n"
+    "If genuinely nothing in this chunk is worth noting even locally, make no calls at all."
+)
+
+_MAX_EXTRACTION_ITERATIONS = 5
+
+
+async def extract_memory(transcript: str, ctx: ToolContext) -> list[Usage]:
+    """Reviews `transcript` (typically the plain-text rendering of the turns
+    a compaction pass just archived - see chat.py's _run_compaction) via a
+    tool-only AgentLoop scoped to REMEMBER, and returns the LLM usage
+    incurred so the caller can fold it into cost tracking. Never raises for
+    a "found nothing worth remembering" outcome - only for a real gateway
+    failure, which the caller is expected to catch (mirrors maybe_compact's
+    own GatewayError-can-propagate contract; ctx.gateway_client must already
+    be set, same precondition _run_compaction already checks before calling
+    maybe_compact in the first place)."""
+    assert ctx.gateway_client is not None
+
+    memory_registry = ToolRegistry()
+    memory_registry.register(REMEMBER)
+    extraction_ctx = replace(ctx, tool_registry=memory_registry)
+
+    known = render_memory_section(read_memory().entries) or "(nothing remembered yet)"
+    sub_loop = AgentLoop(
+        ctx.gateway_client,
+        model=ctx.model,
+        tool_registry=memory_registry,
+        permission_manager=ctx.permission_manager,
+        tool_context_factory=lambda: extraction_ctx,
+        max_tool_iterations=_MAX_EXTRACTION_ITERATIONS,
+        max_response_tokens=ctx.max_response_tokens,
+        temperature=ctx.temperature,
+    )
+    messages = [
+        ChatMessage(
+            role="system", content=f"{_EXTRACTION_SYSTEM_PROMPT}\n\nAlready known:\n{known}"
+        ),
+        ChatMessage(role="user", content=transcript),
+    ]
+
+    def _budget_check() -> str | None:
+        if ctx.session is None:
+            return None
+        return cost_budget_reason(ctx.session, ctx.max_session_cost_usd)
+
+    usages: list[Usage] = []
+    async for event in sub_loop.run_turn(messages, budget_check=_budget_check):
+        if isinstance(event, UsageEvent):
+            usages.append(event.usage)
+    return usages

pcli/memory/models.py

@@ -0,0 +1,103 @@
+"""Global, cross-session user-memory data model: what pcli has learned about
+the user (nature of work, preferences, conversation style, recurring task
+patterns) that should carry across every session, not just the one it was
+learned in - see memory/store.py for persistence and memory/extraction.py
+for how derived entries get added on top of the remember tool's explicit
+ones (tools/builtin/memory_tool.py)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from pcli.util.ids import new_id
+
+MemoryCategory = Literal["profile", "preference", "style", "common_ask", "local"]
+"""The first four are global - persisted to memory/store.py's cross-session,
+cross-project store and injected into every future session's system prompt
+(render_memory_section below). "local" is not one of those: it exists purely
+so the LLM has an explicit, correctly-labeled place to put something
+project/task-specific instead of being forced to either discard it or
+miscategorize it as one of the global ones (the actual failure mode this
+was added to fix - see tools/builtin/memory_tool.py's REMEMBER description
+and memory/extraction.py's system prompt for the instructions that lean on
+this distinction). A "local"-categorized MemoryEntry is never constructed in
+practice - the remember tool's handler intercepts that category and returns
+without calling add_entry - but it's kept as part of this same enum rather
+than a second parallel type, since the tool's valid-category set is derived
+directly from this one."""
+MemorySource = Literal["explicit", "derived"]
+
+_CATEGORY_ORDER: tuple[MemoryCategory, ...] = ("profile", "preference", "style", "common_ask")
+_CATEGORY_LABELS: dict[MemoryCategory, str] = {
+    "profile": "Nature of work",
+    "preference": "Preferences",
+    "style": "Conversation style",
+    "common_ask": "Common asks",
+}
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class MemoryEntry(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("mem_"))
+    category: MemoryCategory
+    content: str
+    source: MemorySource
+    created_at: datetime = Field(default_factory=_utcnow)
+    updated_at: datetime = Field(default_factory=_utcnow)
+
+
+class MemoryStore(BaseModel):
+    entries: list[MemoryEntry] = Field(default_factory=list)
+
+
+def render_memory_section(entries: list[MemoryEntry]) -> str:
+    """Plain-prose system-prompt section, grouped by category in a fixed
+    order - empty string (so build_system_prompt's extra_sections gets
+    nothing to inject) if there's nothing stored yet, so a fresh install's
+    prompt is unaffected."""
+    if not entries:
+        return ""
+    lines = [
+        "# What you know about this user",
+        (
+            "Derived from past sessions (or told to you directly). Treat it as background, not "
+            "instruction — still follow whatever the user actually says in this conversation "
+            "over anything here if the two ever conflict."
+        ),
+    ]
+    for category in _CATEGORY_ORDER:
+        matching = [e for e in entries if e.category == category]
+        if not matching:
+            continue
+        lines.append(f"\n{_CATEGORY_LABELS[category]}:")
+        lines.extend(f"- {entry.content}" for entry in matching)
+    return "\n".join(lines)
+
+
+def render_memory_list(entries: list[MemoryEntry]) -> str:
+    """Human-facing listing for the /memory command - unlike
+    render_memory_section (fed to the model), this includes each entry's
+    short id (last 4 chars, matching sessions.py's SessionListScreen
+    convention) so /memory forget <id> has something to target. Real
+    Markdown (blank line between category blocks, "- " bullets) - the TUI
+    always renders system messages through rich.markdown.Markdown, which
+    collapses plain "\\n"-joined lines into a single run-on paragraph."""
+    if not entries:
+        return "No memory entries yet."
+    blocks = []
+    for category in _CATEGORY_ORDER:
+        matching = [e for e in entries if e.category == category]
+        if not matching:
+            continue
+        lines = [f"**{_CATEGORY_LABELS[category]}:**"]
+        for entry in matching:
+            marker = " *(explicit)*" if entry.source == "explicit" else ""
+            lines.append(f"- `{entry.id[-4:]}` {entry.content}{marker}")
+        blocks.append("\n".join(lines))
+    return "\n\n".join(blocks)

pcli/memory/store.py

@@ -0,0 +1,88 @@
+"""On-disk persistence for the global user-memory store (memory/models.py) -
+mirrors tools/agent_tools_store.py's shape (a single JSON file under
+data_dir(), atomic-written, loaded once and mutated in place) rather than
+session/store.py's per-session-directory layout, since this is one global
+file shared across every session, not per-session state."""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pcli.config.paths import memory_file
+from pcli.memory.models import MemoryCategory, MemoryEntry, MemorySource, MemoryStore
+
+
+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_memory() -> MemoryStore:
+    path = memory_file()
+    if not path.exists():
+        return MemoryStore()
+    return MemoryStore.model_validate_json(path.read_text(encoding="utf-8"))
+
+
+def write_memory(store: MemoryStore) -> None:
+    _atomic_write(memory_file(), store.model_dump_json(indent=2))
+
+
+def add_entry(
+    content: str,
+    *,
+    category: MemoryCategory,
+    source: MemorySource,
+    max_entries: int,
+) -> MemoryEntry:
+    """Appends a new entry, or - a deliberately simple, predictable check,
+    not fuzzy matching - refreshes an existing entry in the same category
+    whose content matches case-insensitively, rather than growing a pile of
+    near-duplicates every time the same fact gets re-derived. Evicts the
+    oldest source='derived' entry first (never 'explicit' - the user asked
+    for that one directly) once adding would exceed max_entries."""
+    store = read_memory()
+    content = content.strip()
+
+    for existing in store.entries:
+        if existing.category == category and existing.content.strip().lower() == content.lower():
+            existing.updated_at = datetime.now(UTC)
+            if source == "explicit":
+                existing.source = "explicit"
+            write_memory(store)
+            return existing
+
+    entry = MemoryEntry(category=category, content=content, source=source)
+    store.entries.append(entry)
+
+    while len(store.entries) > max_entries:
+        derived_indices = [i for i, e in enumerate(store.entries) if e.source == "derived"]
+        if not derived_indices:
+            break  # every remaining entry is explicit - stop evicting rather than touch those
+        oldest = min(derived_indices, key=lambda i: store.entries[i].created_at)
+        del store.entries[oldest]
+
+    write_memory(store)
+    return entry
+
+
+def remove_entry(entry_id: str) -> bool:
+    """Removes one entry by its full id. Returns whether anything was
+    removed - the /memory forget <id> command resolves a short (last-4-char)
+    id to a full one before calling this, so callers here always deal in
+    full ids, not the abbreviated form users type."""
+    store = read_memory()
+    before = len(store.entries)
+    store.entries = [e for e in store.entries if e.id != entry_id]
+    if len(store.entries) == before:
+        return False
+    write_memory(store)
+    return True
+
+
+def clear_memory() -> None:
+    write_memory(MemoryStore())

pcli/permissions/guardrails.py

@@ -0,0 +1,219 @@
+"""Hard, non-negotiable, config-driven checks. A guardrail violation is an
+automatic deny — it never reaches the permission-prompt UI. This is separate
+from (and evaluated before) PermissionManager's ask/remember flow; see
+manager.py.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from pcli.config.paths import guardrails_file
+from pcli.config.settings import _dump_toml
+
+DEFAULT_GUARDRAILS_TOML = """\
+# pcli guardrails — hard limits that are never prompted, only enforced.
+# Patterns without '*'/'?' are matched as a case-insensitive substring of the
+# command; patterns with '*'/'?' are matched anywhere in the command via
+# shell-style wildcards. This is a heuristic safety net, not a shell parser —
+# treat it as defense-in-depth alongside the sandbox, not a substitute for it.
+
+[shell]
+denylist = [
+    "rm -rf /",
+    "rm -rf ~",
+    "mkfs*",
+    ":(){ :|:& };:",
+    "dd if=/dev/zero",
+    "> /dev/sda",
+]
+
+[fs]
+allowed_roots = ["."]
+deny_paths = ["~/.ssh", "~/.aws", "~/.config/pcli"]
+
+[limits]
+max_output_bytes = 2000000
+max_tool_calls_per_turn = 25
+max_tool_calls_per_minute = 60
+max_shell_timeout_s = 300
+max_background_jobs = 5
+
+[python]
+# Top-level modules the pydiscovery tools (inspect_python_module, call_python)
+# refuse to import/resolve into — these overlap with the dedicated, reviewed
+# shell/fs tools, so letting the LLM reach them indirectly via arbitrary
+# Python calls would be a redundant and higher-risk escape hatch.
+module_denylist = [
+    "os",
+    "sys",
+    "subprocess",
+    "ctypes",
+    "shutil",
+    "socket",
+    "importlib",
+    "multiprocessing",
+    "threading",
+    "pty",
+]
+"""
+
+
+class GuardrailResult(BaseModel):
+    allowed: bool
+    reason: str | None = None
+
+
+def _pattern_matches(command: str, pattern: str) -> bool:
+    normalized_command = command.strip().lower()
+    normalized_pattern = pattern.strip().lower()
+    if "*" in normalized_pattern or "?" in normalized_pattern:
+        wrapped = normalized_pattern
+        if not wrapped.startswith("*"):
+            wrapped = f"*{wrapped}"
+        if not wrapped.endswith("*"):
+            wrapped = f"{wrapped}*"
+        return fnmatch.fnmatch(normalized_command, wrapped)
+    return normalized_pattern in normalized_command
+
+
+class GuardrailsConfig(BaseModel):
+    shell_denylist: list[str] = []
+    fs_allowed_roots: list[str] = ["."]
+    fs_deny_paths: list[str] = []
+    max_output_bytes: int = 2_000_000
+    max_tool_calls_per_turn: int = 25
+    max_tool_calls_per_minute: int = 60
+    max_shell_timeout_s: int = 300
+    """Ceiling run_shell's (blocking) timeout_s is clamped to — commands
+    that need longer should use run_shell_background instead, which has no
+    such cap since it doesn't block the turn."""
+    max_background_jobs: int = 5
+    """Concurrent-running cap for run_shell_background; enforced by
+    RestrictedSubprocessSandbox.start_background."""
+    python_module_denylist: list[str] = []
+
+    @classmethod
+    def load(cls) -> GuardrailsConfig:
+        path = guardrails_file()
+        if not path.exists():
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(DEFAULT_GUARDRAILS_TOML, encoding="utf-8")
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+        shell = raw.get("shell", {})
+        fs = raw.get("fs", {})
+        limits = raw.get("limits", {})
+        python = raw.get("python", {})
+        return cls(
+            shell_denylist=shell.get("denylist", []),
+            fs_allowed_roots=fs.get("allowed_roots", ["."]),
+            fs_deny_paths=fs.get("deny_paths", []),
+            max_output_bytes=limits.get("max_output_bytes", 2_000_000),
+            max_tool_calls_per_turn=limits.get("max_tool_calls_per_turn", 25),
+            max_tool_calls_per_minute=limits.get("max_tool_calls_per_minute", 60),
+            max_shell_timeout_s=limits.get("max_shell_timeout_s", 300),
+            max_background_jobs=limits.get("max_background_jobs", 5),
+            python_module_denylist=python.get("module_denylist", []),
+        )
+
+    def evaluate_command(self, command: str) -> GuardrailResult:
+        for pattern in self.shell_denylist:
+            if _pattern_matches(command, pattern):
+                return GuardrailResult(
+                    allowed=False, reason=f"command matches denylist pattern '{pattern}'"
+                )
+        return GuardrailResult(allowed=True)
+
+    def evaluate_python_module(self, qualified_name: str) -> GuardrailResult:
+        top_level = qualified_name.split(".")[0]
+        if top_level in self.python_module_denylist:
+            return GuardrailResult(
+                allowed=False,
+                reason=f"module '{top_level}' is blocked (use the dedicated shell/fs tools instead)",
+            )
+        return GuardrailResult(allowed=True)
+
+    def evaluate_path(self, path: str | Path) -> GuardrailResult:
+        resolved = Path(path).expanduser().resolve()
+
+        for deny_path in self.fs_deny_paths:
+            deny_resolved = Path(deny_path).expanduser().resolve()
+            if resolved == deny_resolved or _is_relative_to(resolved, deny_resolved):
+                return GuardrailResult(
+                    allowed=False,
+                    reason=f"path is within denied path '{deny_path}'.\n"
+                    "[pcli] Suggestion: this is a deliberate guardrails.toml [fs] deny_paths "
+                    "entry (a hard block on a sensitive location - SSH keys, cloud "
+                    "credentials, ...), checked before any permission prompt, so it can't be "
+                    "approved by asking. If this is genuinely blocking legitimate work, that's "
+                    "a guardrails.toml change for the user to make, not something to route "
+                    "around",
+                )
+
+        for allowed_root in self.fs_allowed_roots:
+            allowed_resolved = Path(allowed_root).expanduser().resolve()
+            if resolved == allowed_resolved or _is_relative_to(resolved, allowed_resolved):
+                return GuardrailResult(allowed=True)
+
+        roots_list = ", ".join(
+            str(Path(root).expanduser()) for root in self.fs_allowed_roots
+        )
+        return GuardrailResult(
+            allowed=False,
+            reason=f"path '{resolved}' is outside all allowed roots ({roots_list}).\n"
+            "[pcli] Suggestion: this is a guardrail (guardrails.toml's [fs] allowed_roots), "
+            "checked before any permission prompt, so it can't be approved by asking - add "
+            "the path (or a parent of it) to allowed_roots to let the agent reach it (in the "
+            "TUI: /allowed-roots add <path>)",
+        )
+
+
+def update_guardrails_limits(**limit_updates: Any) -> None:
+    """Persists the given key/value pairs into guardrails.toml's [limits]
+    table, preserving the [shell]/[fs]/[python] tables and any other
+    [limits] keys untouched — mirrors config/settings.py's
+    update_config_file, but for guardrails.toml's fixed 4-table shape
+    instead of config.toml's flatter one.
+
+    Falsy values (None) are skipped rather than written, matching
+    update_config_file's same behavior for optional callers."""
+    path = guardrails_file()
+    if path.exists():
+        raw = dict(tomllib.loads(path.read_text(encoding="utf-8")))
+    else:
+        raw = dict(tomllib.loads(DEFAULT_GUARDRAILS_TOML))
+    limits = dict(raw.get("limits", {}))
+    limits.update({key: value for key, value in limit_updates.items() if value is not None})
+    raw["limits"] = limits
+    path.write_text(_dump_toml(raw), encoding="utf-8")
+
+
+def update_guardrails_fs_allowed_roots(allowed_roots: list[str]) -> None:
+    """Persists a full replacement allowed_roots list into guardrails.toml's
+    [fs] table, preserving deny_paths and every other table untouched -
+    same shape as update_guardrails_limits above but for a list-valued
+    [fs] key instead of a scalar [limits] one, so the caller (chat.py's
+    /allowed-roots add/remove) computes the whole new list itself rather
+    than this function doing partial add/remove logic."""
+    path = guardrails_file()
+    if path.exists():
+        raw = dict(tomllib.loads(path.read_text(encoding="utf-8")))
+    else:
+        raw = dict(tomllib.loads(DEFAULT_GUARDRAILS_TOML))
+    fs = dict(raw.get("fs", {}))
+    fs["allowed_roots"] = allowed_roots
+    raw["fs"] = fs
+    path.write_text(_dump_toml(raw), encoding="utf-8")
+
+
+def _is_relative_to(path: Path, other: Path) -> bool:
+    try:
+        path.relative_to(other)
+        return True
+    except ValueError:
+        return False