seedcode-cli 6.1.5__py3-none-any.whl

seedcode/memory/manager.py

@@ -0,0 +1,47 @@
+"""Management of the saved-session collection: listing saved transcripts.
+
+Where :mod:`seedcode.memory.storage` persists a single live session, this
+module reads back across all saved sessions on disk (used by /history).
+"""
+
+from __future__ import annotations
+
+import json
+
+from ..utils.helpers import history_dir
+
+
+def list_sessions(provider_id: str = "") -> list[tuple[str, int]]:
+    """Return ``(session_id, message_count)`` for saved sessions, newest first.
+
+    With ``provider_id``, only that provider's own history is listed.
+    """
+    sessions: list[tuple[str, int]] = []
+    for path in sorted(history_dir(provider_id).glob("session-*.json"), reverse=True):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            sid = path.stem.replace("session-", "")
+            sessions.append((sid, len(data)))
+        except (json.JSONDecodeError, OSError):
+            continue
+    return sessions
+
+
+def load_session(provider_id: str, session_id: str) -> list[dict]:
+    """Load one saved transcript as raw message dicts ([] on any failure)."""
+    path = history_dir(provider_id) / f"session-{session_id}.json"
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return data if isinstance(data, list) else []
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+def delete_session(provider_id: str, session_id: str) -> bool:
+    """Delete one saved transcript; True when the file is gone afterwards."""
+    path = history_dir(provider_id) / f"session-{session_id}.json"
+    try:
+        path.unlink(missing_ok=True)
+        return True
+    except OSError:
+        return False

seedcode/memory/storage.py

@@ -0,0 +1,38 @@
+"""Conversation history persistence.
+
+Each session is stored as a JSON file under ``~/.seedcode/history``. History is
+best-effort: failures to read or write are swallowed so a disk hiccup never
+interrupts a chat.
+"""
+
+from __future__ import annotations
+
+import json
+
+from ..core.models import Message
+from ..utils.helpers import history_dir, restrict_permissions, session_id
+
+
+class HistoryStore:
+    """Append-friendly JSON transcript for a single chat session.
+
+    Transcripts are stored per provider (``history/<provider>/...``) so each
+    backend keeps its own independent history.
+    """
+
+    def __init__(self, sid: str | None = None, provider_id: str = "") -> None:
+        self.session_id = sid or session_id()
+        self.provider_id = provider_id
+        self.path = history_dir(provider_id) / f"session-{self.session_id}.json"
+
+    def save(self, messages: list[Message]) -> None:
+        """Write the full transcript (excluding system messages) to disk."""
+        payload = [m.model_dump() for m in messages if m.role != "system"]
+        try:
+            self.path.write_text(
+                json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8"
+            )
+            restrict_permissions(self.path)
+        except OSError:
+            # History is a convenience, never a hard requirement.
+            pass

seedcode/memory/store.py

@@ -0,0 +1,257 @@
+"""Persistent local memory: indexed JSON records under ``~/.seedcode/memory``.
+
+Design rules the tests pin:
+
+* **Structured records, not transcripts.** Each record is a small JSON file
+  (``<namespace>/<name>.json``) plus a per-namespace ``index.json`` holding
+  id/summary/tags/timestamps. Retrieval reads the *index*, then loads only
+  the referenced records — never the whole directory.
+* **Namespaces.** ``sessions`` (task records), ``desktop`` (apps, monitors,
+  environment), ``user`` (operational preferences), ``web`` (extracted
+  pages), ``files`` (downloaded/extracted artifacts).
+* **Secret filtering.** Keys matching secret-ish names (password, token,
+  api_key, cookie, secret...) are rejected at write time with
+  :class:`SecurityError`; redaction masks values in anything that slips
+  through nested structures. Secrets belong in a credential manager, never
+  in memory JSON.
+* **Local-first.** Everything lives under the per-user app dir; nothing
+  uploads. Corruption is contained: a bad record/index degrades to empty
+  for that namespace without touching the others.
+
+Storage is atomic (write-to-temp + replace) so a crash never leaves a
+half-written record behind.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ..core.errors import SecurityError
+from ..utils.helpers import app_dir
+
+NAMESPACES = ("sessions", "desktop", "user", "web", "files")
+
+# Keys that must never be persisted into normal memory.
+_SECRET_KEY_RE = re.compile(
+    r"(password|passwd|pwd|secret|token|api[_-]?key|apikey|credential|"
+    r"auth|cookie|session[_-]?id|private[_-]?key|access[_-]?key)",
+    re.IGNORECASE,
+)
+
+
+def mask_secret(value: Any) -> str:
+    """Mask a secret-ish value for logs/echoes: keep 2 leading chars."""
+    text = str(value)
+    if len(text) <= 4:
+        return "*" * len(text)
+    return text[:2] + "*" * (len(text) - 2)
+
+
+@dataclass(slots=True)
+class MemoryRecord:
+    """One retrievable memory entry (metadata lives in the index)."""
+
+    id: str
+    namespace: str
+    summary: str
+    data: dict[str, Any] = field(default_factory=dict)
+    tags: list[str] = field(default_factory=list)
+    created_at: float = field(default_factory=time.time)
+
+
+def _assert_no_secrets(data: Any, path: str = "") -> None:
+    """Reject nested secret-looking keys before anything touches disk."""
+    if isinstance(data, dict):
+        for key, value in data.items():
+            here = f"{path}.{key}" if path else str(key)
+            if _SECRET_KEY_RE.search(str(key)):
+                raise SecurityError(
+                    f"Refusing to store a secret-looking field ('{here}') in "
+                    "memory. Credentials belong in a credential manager."
+                )
+            _assert_no_secrets(value, here)
+    elif isinstance(data, list):
+        for i, item in enumerate(data):
+            _assert_no_secrets(item, f"{path}[{i}]")
+
+
+class MemoryStore:
+    """Namespaced, indexed, atomic JSON record store."""
+
+    def __init__(self, root: Path | None = None) -> None:
+        self._root = root or (app_dir() / "memory")
+        try:
+            self._root.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            pass  # writes will fail later and are handled per-call
+
+    # --- paths ---------------------------------------------------------------
+    def _ns_dir(self, namespace: str) -> Path:
+        ns = namespace.strip().lower()
+        if ns not in NAMESPACES:
+            raise ValueError(
+                f"Unknown memory namespace '{namespace}'. Choose one of: "
+                f"{', '.join(NAMESPACES)}."
+            )
+        return self._root / ns
+
+    def _index_path(self, namespace: str) -> Path:
+        return self._ns_dir(namespace) / "index.json"
+
+    def _record_path(self, namespace: str, record_id: str) -> Path:
+        safe = re.sub(r"[^a-zA-Z0-9._-]", "_", record_id)[:80] or "record"
+        return self._ns_dir(namespace) / f"{safe}.json"
+
+    # --- atomic IO -------------------------------------------------------------
+    @staticmethod
+    def _write_atomic(path: Path, payload: dict[str, Any]) -> bool:
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            tmp.write_text(
+                json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8"
+            )
+            tmp.replace(path)
+            return True
+        except (OSError, ValueError):
+            return False
+
+    @staticmethod
+    def _read_json(path: Path) -> dict[str, Any] | None:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            return data if isinstance(data, dict) else None
+        except (OSError, ValueError):
+            return None  # corrupt or missing -> treated as empty
+
+    # --- index -----------------------------------------------------------------
+    def _load_index(self, namespace: str) -> dict[str, Any]:
+        data = self._read_json(self._index_path(namespace))
+        if data is None:
+            return {"records": {}}
+        records = data.get("records")
+        return {"records": records} if isinstance(records, dict) else {"records": {}}
+
+    def _save_index(self, namespace: str, index: dict[str, Any]) -> bool:
+        return self._write_atomic(self._index_path(namespace), index)
+
+    # --- public API ----------------------------------------------------------------
+    def put(
+        self,
+        namespace: str,
+        record_id: str,
+        summary: str,
+        data: dict[str, Any] | None = None,
+        tags: list[str] | None = None,
+    ) -> bool:
+        """Store a record + index entry (secret-checked). False on IO failure."""
+        _assert_no_secrets(data or {})
+        _assert_no_secrets({"summary": summary})
+        record = {
+            "id": record_id,
+            "namespace": namespace,
+            "summary": summary,
+            "tags": list(tags or []),
+            "created_at": time.time(),
+            "data": data or {},
+        }
+        if not self._write_atomic(self._record_path(namespace, record_id), record):
+            return False
+        index = self._load_index(namespace)
+        index["records"][record_id] = {
+            "summary": summary,
+            "tags": list(tags or []),
+            "created_at": record["created_at"],
+        }
+        return self._save_index(namespace, index)
+
+    def get(self, namespace: str, record_id: str) -> MemoryRecord | None:
+        """Load one record by id (None when missing/corrupt)."""
+        raw = self._read_json(self._record_path(namespace, record_id))
+        if raw is None or not isinstance(raw.get("id"), str):
+            return None
+        return MemoryRecord(
+            id=raw["id"],
+            namespace=raw.get("namespace", namespace),
+            summary=raw.get("summary", ""),
+            data=raw.get("data", {}) if isinstance(raw.get("data"), dict) else {},
+            tags=raw.get("tags", []) if isinstance(raw.get("tags"), list) else [],
+            created_at=float(raw.get("created_at", 0.0)),
+        )
+
+    def delete(self, namespace: str, record_id: str) -> bool:
+        """Remove a record and its index entry."""
+        try:
+            self._record_path(namespace, record_id).unlink(missing_ok=True)
+        except OSError:
+            return False
+        index = self._load_index(namespace)
+        index["records"].pop(record_id, None)
+        return self._save_index(namespace, index)
+
+    def query(
+        self, namespace: str, *, text: str = "", tags: list[str] | None = None,
+        limit: int = 10,
+    ) -> list[dict[str, Any]]:
+        """Index-level search (no record loads): newest first, filtered.
+
+        Matches on summary + tags + id. Returns index entries
+        ``{id, summary, tags, created_at}`` — callers load full records
+        selectively via :meth:`get`.
+        """
+        index = self._load_index(namespace)
+        wanted_tags = {t.lower() for t in (tags or [])}
+        needle = (text or "").strip().lower()
+        hits: list[dict[str, Any]] = []
+        for record_id, entry in index["records"].items():
+            if not isinstance(entry, dict):
+                continue
+            entry_tags = [str(t).lower() for t in entry.get("tags", [])]
+            if wanted_tags and not wanted_tags.issubset(set(entry_tags)):
+                continue
+            haystack = " ".join([
+                record_id, str(entry.get("summary", "")), " ".join(entry_tags),
+            ]).lower()
+            if needle and needle not in haystack:
+                continue
+            hits.append({
+                "id": record_id,
+                "summary": entry.get("summary", ""),
+                "tags": entry.get("tags", []),
+                "created_at": entry.get("created_at", 0.0),
+            })
+        hits.sort(key=lambda h: h["created_at"], reverse=True)
+        return hits[: max(1, limit)]
+
+    def namespaces(self) -> list[str]:
+        """Namespaces that exist on disk (of the known set)."""
+        return [ns for ns in NAMESPACES if self._ns_dir(ns).is_dir()]
+
+
+# --- process-wide store ---------------------------------------------------------------
+_STORE: MemoryStore | None = None
+
+
+def memory_store(root: Path | None = None) -> MemoryStore:
+    """The process-wide :class:`MemoryStore` (root injectable for tests)."""
+    global _STORE
+    if _STORE is None or root is not None:
+        if _STORE is None:
+            _STORE = MemoryStore(root)
+    return _STORE
+
+
+def reset_memory_store() -> None:
+    global _STORE
+    _STORE = None
+
+
+__all__ = [
+    "NAMESPACES", "MemoryRecord", "MemoryStore", "mask_secret",
+    "memory_store", "reset_memory_store",
+]

seedcode/tools/__init__.py

@@ -0,0 +1,35 @@
+"""Tool engine for Seed Code agent mode.
+
+Tools are the actions the agent may take on the user's machine: reading and
+writing files, searching, running commands, and using git. Every tool is
+registered in a table (mirroring the slash-command registry) and every
+execution passes through the :class:`~seedcode.tools.permissions.PermissionManager`
+first, so what the agent may touch is decided in exactly one place.
+"""
+
+from __future__ import annotations
+
+from .base import Tool, ToolError, ToolResult, TOOL_REGISTRY, get_tool, tool_manifest
+from .permissions import (
+    PermissionError_,
+    PermissionLevel,
+    PermissionManager,
+    PermissionMode,
+)
+
+# Import tool modules for their registration side effects (same pattern as
+# seedcode.commands): each module's @register calls populate TOOL_REGISTRY.
+from . import desktop, filesystem, git, patch, search, terminal  # noqa: E402,F401
+
+__all__ = [
+    "PermissionError_",
+    "PermissionLevel",
+    "PermissionManager",
+    "PermissionMode",
+    "TOOL_REGISTRY",
+    "Tool",
+    "ToolError",
+    "ToolResult",
+    "get_tool",
+    "tool_manifest",
+]

seedcode/tools/base.py

@@ -0,0 +1,179 @@
+"""Tool contracts and registry for agent mode.
+
+A tool is a named action with a JSON-friendly argument schema and a runner.
+The registry is the single source of truth for what the agent can do; the
+system prompt shown to the model is generated from it (:func:`tool_manifest`),
+so the documentation the model sees can never drift from the implementation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from .permissions import PermissionManager
+
+# Output larger than this is truncated before it re-enters the conversation,
+# keeping a single tool call from blowing the model's context window.
+MAX_OUTPUT_CHARS = 12_000
+
+
+class ToolError(Exception):
+    """A tool could not complete; the message is fed back to the model."""
+
+
+def int_arg(args: dict[str, Any], name: str, default: int, lo: int, hi: int) -> int:
+    """Coerce an integer argument, clamped to [lo, hi].
+
+    Models sometimes send numbers as strings or send junk; a friendly
+    :class:`ToolError` beats the raw ``ValueError`` the generic crash guard
+    would otherwise surface.
+    """
+    raw = args.get(name, default)
+    try:
+        value = int(raw)
+    except (TypeError, ValueError):
+        raise ToolError(f"Argument '{name}' must be a whole number, got {raw!r}.") from None
+    return max(lo, min(value, hi))
+
+
+@dataclass(slots=True)
+class ToolResult:
+    """Outcome of one tool execution, fed back into the conversation."""
+
+    ok: bool
+    output: str
+
+    def for_model(self) -> str:
+        """Result text as the model sees it, truncated to a safe size."""
+        text = self.output if self.output.strip() else "(no output)"
+        if len(text) > MAX_OUTPUT_CHARS:
+            omitted = len(text) - MAX_OUTPUT_CHARS
+            text = text[:MAX_OUTPUT_CHARS] + f"\n... [truncated {omitted} chars]"
+        status = "OK" if self.ok else "ERROR"
+        return f"[{status}] {text}"
+
+
+Runner = Callable[["PermissionManager", dict[str, Any]], ToolResult]
+
+
+@dataclass(slots=True)
+class Tool:
+    """One agent-callable action."""
+
+    name: str
+    description: str
+    # arg name -> one-line description; "(optional)" marks optional args.
+    args: dict[str, str]
+    # True when the tool changes files or system state (drives permissions).
+    mutates: bool
+    runner: Runner
+    # Which engine the tool belongs to: "core" (files/search/git/shell) or
+    # "desktop" (the Computer Engine). Drives manifest filtering so plain
+    # agent mode never advertises desktop tools.
+    group: str = "core"
+    # arg name -> JSON-schema type for non-string args ("integer",
+    # "boolean", ...). Unlisted args are strings. Drives native tool schemas.
+    types: dict[str, str] = field(default_factory=dict)
+
+    def run(self, permissions: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+        missing = [
+            name
+            for name, desc in self.args.items()
+            if "(optional)" not in desc and name not in args
+        ]
+        if missing:
+            raise ToolError(
+                f"Tool '{self.name}' is missing required argument(s): {', '.join(missing)}."
+            )
+        return self.runner(permissions, args)
+
+
+TOOL_REGISTRY: dict[str, Tool] = {}
+
+
+def register(
+    name: str,
+    description: str,
+    args: dict[str, str],
+    *,
+    mutates: bool,
+    group: str = "core",
+    types: dict[str, str] | None = None,
+) -> Callable[[Runner], Runner]:
+    """Decorator registering a runner in the tool table."""
+
+    def wrap(runner: Runner) -> Runner:
+        TOOL_REGISTRY[name] = Tool(
+            name=name,
+            description=description,
+            args=args,
+            mutates=mutates,
+            runner=runner,
+            group=group,
+            types=types or {},
+        )
+        return runner
+
+    return wrap
+
+
+def get_tool(name: str) -> Tool:
+    tool = TOOL_REGISTRY.get((name or "").strip().lower())
+    if tool is None:
+        known = ", ".join(sorted(TOOL_REGISTRY))
+        raise ToolError(f"Unknown tool '{name}'. Available tools: {known}.")
+    return tool
+
+
+def tool_manifest(groups: tuple[str, ...] = ("core",)) -> str:
+    """Tool documentation injected into the agent system prompt.
+
+    Only tools in ``groups`` are listed, so what the model is told matches
+    what the session actually allows (e.g. desktop tools only appear when
+    desktop mode is on).
+    """
+    lines = []
+    for tool in sorted(TOOL_REGISTRY.values(), key=lambda t: t.name):
+        if tool.group not in groups:
+            continue
+        arg_desc = ", ".join(f'"{a}": {d}' for a, d in tool.args.items()) or "none"
+        lines.append(f"- {tool.name}: {tool.description}\n  args: {arg_desc}")
+    return "\n".join(lines)
+
+
+def tool_specs(groups: tuple[str, ...] = ("core",)) -> list[dict[str, Any]]:
+    """Neutral name/description/parameters specs for native tool calling.
+
+    Generated from the same registry as :func:`tool_manifest`, so the schema
+    a provider sends can never drift from the implementation. Each entry is
+    ``{"name", "description", "parameters"}`` with ``parameters`` a
+    JSON-schema object; args whose description lacks "(optional)" are
+    required.
+    """
+    specs: list[dict[str, Any]] = []
+    for tool in sorted(TOOL_REGISTRY.values(), key=lambda t: t.name):
+        if tool.group not in groups:
+            continue
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+        for arg, desc in tool.args.items():
+            properties[arg] = {
+                "type": tool.types.get(arg, "string"),
+                "description": desc,
+            }
+            if "(optional)" not in desc:
+                required.append(arg)
+        specs.append(
+            {
+                "name": tool.name,
+                "description": tool.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required,
+                },
+            }
+        )
+    return specs