zettcode-engine 0.3.4__py3-none-any.whl

zettcode/engine/permission/__init__.py

@@ -0,0 +1,197 @@
+"""How much of the shell the agent may use without asking, and what enforces it.
+
+Four levels, from the strictest to the loosest, and they are one setting rather
+than four features because the thing they decide is one question — *when a shell
+command arrives, who answers?*
+
+=======  ===============================================================
+``deny``   Nobody runs it: the command fails and the model is told why.
+``ask``    The reader answers each one (the default, and what the prompt does).
+``safe``   Every command runs, inside an operating-system sandbox that lets it
+           write the workspace and ``/tmp`` only (:mod:`.sandbox`). Where the
+           machine has no sandbox: read-only commands run and the rest ask.
+``full``   Every command runs with the user's own access. (Formerly ``auto``.)
+=======  ===============================================================
+
+The level is shared state between the shell, which changes it, and two things on
+the agent's side that read it on every shell call: the approval memory, which is
+what lets ``safe`` and ``full`` skip the prompt, and :class:`ShellDenyExtension`,
+which is what makes ``deny`` refuse. Neither keeps its own copy, so a change takes
+effect on the next command, including one the model is about to issue in the
+request that is running now.
+
+Only the shell is governed. The file tools, the MCP tools, and the web tools are
+not behind a prompt in this application and this setting does not put them behind
+one: the level is named for what it controls, and the picker says so.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from zett_agent.agent import AgentRunContext
+from zett_agent.extensions.base import AgentExtension, ToolCallNext
+from zett_agent.extensions.shell_approval import SHELL_APPROVAL_TOOL_NAME, ShellApprovalMode
+from zett_agent.messages import ToolCall
+from zett_agent.sandbox.base import Sandbox
+from zett_agent.tools.base import ToolResult
+
+from zettcode._compat import StrEnum
+
+from ..tools.boundary import Boundary, Sandboxer
+from .readonly import is_read_only
+from .sandbox import ShellSandbox
+
+
+class Permission(StrEnum):
+    """How much of the shell may run without a person answering for it.
+
+    Attributes:
+        DENY: No shell command runs; the model is told, and can carry on without.
+        ASK: Every command that is not already approved is put to the reader.
+        SAFE: Every command runs unasked, in a sandbox that writes only the workspace and the temporary
+            directory. On a machine with no sandbox: only commands that cannot change anything run unasked.
+        FULL: Every command runs unasked with the user's own access.
+        AUTO: The old name of ``FULL``, kept so code and config written before the rename still work.
+    """
+
+    DENY = "deny"
+    ASK = "ask"
+    SAFE = "safe"
+    FULL = "full"
+    AUTO = "full"
+
+
+#: The levels strictest first, which is the order the picker lists them in.
+PERMISSION_LEVELS: tuple[Permission, ...] = (Permission.DENY, Permission.ASK, Permission.SAFE, Permission.FULL)
+
+#: A shell command refused by ``deny``, as the model reads it. It says what the
+#: reader did and what is still open to the model, because a bare "refused" sends
+#: a model looking for a way around it.
+DENIED_MESSAGE = (
+    "Shell commands are turned off by the user (permission: deny). "
+    "Use the file tools to read and edit, or tell the user what command you need."
+)
+
+
+def parse_permission(name: str) -> Permission:
+    """Return the level a user typed, or raise with the names that are valid.
+
+    Args:
+        name: A level's name; case and surrounding space do not matter. ``auto``, the name ``full`` had before
+            it was renamed, is still taken.
+
+    Raises:
+        ValueError: The name is not one of the four, and the message lists them.
+    """
+    wanted = name.strip().lower()
+    try:
+        return Permission("full" if wanted == "auto" else wanted)
+    except ValueError:
+        levels = ", ".join(level.value for level in PERMISSION_LEVELS)
+        raise ValueError(f"Unknown permission: {name}. Try one of: {levels}") from None
+
+
+class ShellPolicy(Boundary):
+    """The level in force, and the question each level asks of a command.
+
+    One instance is shared by the shell, the approval memory, and the deny
+    extension. It holds a single enum member, which is read and replaced
+    atomically, so the shell thread changing it and the agent's loop reading it
+    need no lock: a command in flight sees the old level or the new one, never a
+    mixture.
+    """
+
+    def __init__(
+        self,
+        level: Permission = Permission.ASK,
+        workspace: Path | None = None,
+        sandbox: ShellSandbox | None = None,
+    ) -> None:
+        """Start at a level, for commands that run in a workspace.
+
+        Args:
+            level: The level in force until it is changed.
+            workspace: Directory commands run in; ``git`` is only ever judged
+                read-only against a repository that can be found from here.
+            sandbox: What ``safe`` runs commands in. ``None`` builds the default for ``workspace`` (no network),
+                and with no workspace there is no sandbox at all.
+        """
+        self.level = level
+        self.workspace = workspace
+        self.sandbox = sandbox if sandbox is not None else (ShellSandbox(workspace) if workspace else None)
+
+    @property
+    def sandboxed(self) -> bool:
+        """Return whether a command is run inside the sandbox right now: level ``safe`` on a machine that has one."""
+        return self.sandbox_now() is not None
+
+    def sandbox_now(self) -> Sandboxer | None:
+        """Return the sandbox the next command runs in, or ``None`` when it runs as given."""
+        if self.level is Permission.SAFE and self.sandbox is not None and self.sandbox.available:
+            return self.sandbox
+        return None
+
+    def jit_sandbox(self) -> Sandbox | None:
+        """Return the boundary code the model writes runs in, or ``None`` when it gets the user's own access.
+
+        One answer for one decision: the just-in-time harness asks this instead of reading the level itself, so
+        the shell and the code the model wrote cannot disagree about what a level means. `full` is the level that
+        grants the model the reader's access, so nothing is left for a boundary to hold back; every other level
+        bounds it with the boundary `safe` uses, and a machine with no sandbox has nothing to pass on — the
+        reader is told, at the level that claimed a boundary (see :meth:`sandbox_missing`).
+        """
+        if self.level is Permission.FULL:
+            return None
+        return self.sandbox.boundary if self.sandbox is not None else None
+
+    def sandbox_missing(self) -> bool:
+        """Return whether the level in force promises a boundary this machine does not have."""
+        return self.level is not Permission.FULL and not (self.sandbox is not None and self.sandbox.available)
+
+    @classmethod
+    def from_mode(
+        cls, mode: ShellApprovalMode, workspace: Path | None = None, sandbox: ShellSandbox | None = None
+    ) -> ShellPolicy:
+        """Start at the level the configured approval mode stands for."""
+        return cls(Permission.FULL if mode is ShellApprovalMode.ALLOW_ALL else Permission.ASK, workspace, sandbox)
+
+    def allows_unasked(self, command: str) -> bool:
+        """Return whether this level lets a command run without putting it to the reader.
+
+        ``deny`` never reaches here — the deny extension has already refused —
+        but it answers no all the same, so a caller that asks cannot be told yes
+        by mistake.
+        """
+        if self.level is Permission.FULL:
+            return True
+        if self.level is Permission.SAFE:
+            # The sandbox is the boundary, so any command may run in it. Without one, only a command that
+            # provably changes nothing is trusted.
+            return self.sandboxed or is_read_only(command, self.workspace)
+        return False
+
+
+class ShellDenyExtension(AgentExtension):
+    """Refuse every shell command while the level is ``deny``.
+
+    The approval extension can say yes or ask but has no way to say no on the
+    reader's behalf, and answering "abort" to a prompt that was never shown would
+    mean putting the panel up and tearing it down. So this runs before it, as the
+    outer layer of the onion, and raises into ordinary tool-failure handling: the
+    model sees a failed ``bash`` call whose message says why.
+    """
+
+    #: Before the approval extension, which is the layer that would otherwise put
+    #: the command to the reader.
+    priority = 50
+
+    def __init__(self, policy: ShellPolicy) -> None:
+        """Read the level from the policy the shell changes."""
+        self._policy = policy
+
+    async def on_tool_call(self, context: AgentRunContext, call: ToolCall, call_next: ToolCallNext) -> ToolResult:
+        """Let every tool through except a shell command, which ``deny`` refuses."""
+        if self._policy.level is Permission.DENY and call.name == SHELL_APPROVAL_TOOL_NAME:
+            raise PermissionError(DENIED_MESSAGE)
+        return await call_next()

zettcode/engine/permission/approval.py

@@ -0,0 +1,66 @@
+"""What the shell approval prompt is allowed to remember.
+
+``zett-agent``'s shell extension asks for approval through an external event,
+and can remember a decision only when it is given something to remember it in:
+without storage it reports ``remember_supported=False`` and the prompt cannot
+offer "always allow this command".
+
+ZettCode keeps that memory in the process, which is what its prompt promises —
+the exact command is approved for the rest of this run, and the next start
+asks again, exactly like the run-wide policy beside it.
+"""
+
+from __future__ import annotations
+
+from zett_agent.extensions.shell_approval import ShellApprovalMode
+
+from . import ShellPolicy
+
+
+class ShellApprovalMemory:
+    """Approval memory for one process: a policy per session, exact commands.
+
+    This satisfies ``zett-agent``'s ``ShellApprovalStorage``, which the shell
+    extension uses to look up a session's mode and to check and record one
+    approved command.
+
+    The shell extension asks :meth:`is_allowed` before it puts a command to the
+    reader, which makes it the one place a permission level can say "do not ask":
+    ``safe`` answers yes for a command that cannot change anything and ``auto``
+    answers yes for every command, while ``ask`` falls through to the commands the
+    reader approved by hand. ``deny`` is not decided here, because refusing is not
+    a thing this question can express.
+    """
+
+    def __init__(self, policy: ShellPolicy | None = None) -> None:
+        """Start with no session policy and nothing approved.
+
+        Args:
+            policy: The permission level to consult; without one every command
+                is put to the reader, which is what ``ask`` does.
+        """
+        self._modes: dict[str, ShellApprovalMode] = {}
+        self._allowed: set[str] = set()
+        self._policy = policy
+
+    async def get_session_mode(self, session_id: str) -> ShellApprovalMode:
+        """Return a session's policy, which is review until one is set."""
+        return self._modes.get(session_id, ShellApprovalMode.REVIEW)
+
+    async def set_session_mode(self, session_id: str, mode: ShellApprovalMode) -> None:
+        """Record one session's policy for the rest of the process."""
+        self._modes[session_id] = mode
+
+    async def clear_session_mode(self, session_id: str) -> None:
+        """Forget a session's policy, so the next prompt reviews again."""
+        self._modes.pop(session_id, None)
+
+    async def is_allowed(self, session_id: str, command: str) -> bool:
+        """Return whether a command may run without asking: by level, or approved by hand."""
+        if self._policy is not None and self._policy.allows_unasked(command):
+            return True
+        return command in self._allowed
+
+    async def allow_command(self, command: str) -> None:
+        """Remember one exact command for the rest of this run."""
+        self._allowed.add(command)

zettcode/engine/permission/readonly.py

@@ -0,0 +1,435 @@
+"""Which shell commands cannot change anything, so the ``safe`` level may skip asking.
+
+The question this answers is narrow and the answer is fail-closed: a command is
+read-only only when every part of it is recognised, and anything this module does
+not positively know is *not* read-only. A wrong "yes" runs something nobody
+approved; a wrong "no" costs one keypress at the prompt — so the two errors are
+not weighed equally, and every rule below leans the same way.
+
+Three layers, each of which can only say no:
+
+1. **Shape.** The command must be plain words joined by ``|``. The characters
+   that make a shell do more than run a program — ``; & < > ( ) $ ` \\ { } !`` and
+   newlines — are refused outside quotes, and ``$ ` \\ !`` inside double quotes,
+   where the shell still expands them. A word is never *interpreted* here, only
+   split and unquoted, so there is no expansion for a hostile string to hide in.
+2. **Program.** The first word of each pipeline stage must equal a name on a
+   short list of programs that have no way to write a file or run another
+   program, or one of the three that need their arguments checked (``find``,
+   ``rg``, ``git``). Equal, not similar: ``./ls`` is whatever the workspace says
+   it is, and ``LD_PRELOAD=x ls`` is not ``ls``, and neither is on the list.
+3. **Arguments.** For those three, an option is allowed only when it is known to
+   be harmless. ``git`` takes options from an allowlist rather than a denylist
+   because it accepts any unambiguous *abbreviation* of a long option: a denylist
+   that names ``--output`` does not stop ``--outp``, an allowlist that names only
+   whole, harmless options stops both.
+
+What this does **not** do is make reading harmless. A read-only command can still
+print a secret that sits in the workspace; ``safe`` is a promise that nothing will
+change, not that nothing will be seen. And ``git`` reads its own configuration,
+which can name programs to run (``core.fsmonitor``, ``diff.external``, a textconv
+driver): the repository's config file is scanned for those keys, and a repository
+that has any is treated as one ``git`` cannot be trusted in. The user's global git
+configuration is not scanned.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+#: Characters that may appear outside quotes: letters, digits, space, and the
+#: punctuation of paths, options, globs, and numbers. Everything else makes the
+#: command something other than a plain word list, and is refused.
+_UNQUOTED = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 _-./:=,+@%*?[]~^")
+
+#: Characters a double-quoted string still expands, which a literal never does.
+_EXPANDING = frozenset("$`\\!")
+
+#: Programs with no way to write a file or run another program, whatever the
+#: arguments. Each was checked for output-file options, ``-exec``-style options,
+#: and a pager: ``sort -o``, ``uniq in out``, ``sed -i``/``w``/``e``, ``awk``'s
+#: ``system``, ``tee``, ``xargs``, ``env``, and ``file -C`` are all left off for
+#: exactly that reason.
+_PLAIN = frozenset(
+    {
+        "pwd",
+        "ls",
+        "cat",
+        "head",
+        "tail",
+        "wc",
+        "stat",
+        "du",
+        "df",
+        "which",
+        "whoami",
+        "id",
+        "uname",
+        "basename",
+        "dirname",
+        "realpath",
+        "readlink",
+        "echo",
+        "grep",
+        "diff",
+        "cut",
+        "jq",
+    }
+)
+
+#: ``find`` primaries that only match or print. ``-exec``, ``-execdir``, ``-ok``,
+#: ``-okdir``, ``-delete``, and the ``-fprint`` family are absent on purpose: an
+#: option not on this list makes the command one that asks.
+_FIND_OPTIONS = frozenset(
+    {
+        "-H",
+        "-L",
+        "-P",
+        "-name",
+        "-iname",
+        "-path",
+        "-ipath",
+        "-wholename",
+        "-regex",
+        "-iregex",
+        "-type",
+        "-xtype",
+        "-size",
+        "-mtime",
+        "-atime",
+        "-ctime",
+        "-mmin",
+        "-amin",
+        "-cmin",
+        "-newer",
+        "-maxdepth",
+        "-mindepth",
+        "-depth",
+        "-empty",
+        "-perm",
+        "-user",
+        "-group",
+        "-nouser",
+        "-nogroup",
+        "-readable",
+        "-writable",
+        "-executable",
+        "-links",
+        "-inum",
+        "-print",
+        "-print0",
+        "-prune",
+        "-not",
+        "-a",
+        "-o",
+        "-and",
+        "-or",
+        "-true",
+        "-false",
+        "-follow",
+    }
+)
+
+#: Options of ``rg`` that run a program or read a compressed file through one.
+_RG_FORBIDDEN = frozenset({"--pre", "--pre-glob", "--hostname-bin", "--search-zip"})
+
+#: ``git`` subcommands that read the repository and nothing else.
+_GIT_SUBCOMMANDS = frozenset(
+    {
+        "status",
+        "log",
+        "diff",
+        "show",
+        "blame",
+        "ls-files",
+        "ls-tree",
+        "rev-parse",
+        "rev-list",
+        "describe",
+        "shortlog",
+        "cat-file",
+        "merge-base",
+        "name-rev",
+        "show-ref",
+        "diff-tree",
+        "grep",
+        "branch",
+    }
+)
+
+#: Long options of those subcommands that are known to be harmless. Whole names
+#: only: git accepts any unambiguous abbreviation of a long option, so a
+#: shortened ``--outp`` is not here and therefore not allowed, which is the point.
+_GIT_LONG_OPTIONS = frozenset(
+    {
+        "--oneline",
+        "--graph",
+        "--decorate",
+        "--no-decorate",
+        "--stat",
+        "--shortstat",
+        "--numstat",
+        "--name-only",
+        "--name-status",
+        "--patch",
+        "--no-patch",
+        "--cached",
+        "--staged",
+        "--all",
+        "--abbrev-commit",
+        "--abbrev",
+        "--no-color",
+        "--color",
+        "--short",
+        "--long",
+        "--branch",
+        "--porcelain",
+        "--untracked-files",
+        "--ignored",
+        "--format",
+        "--pretty",
+        "--date",
+        "--since",
+        "--until",
+        "--after",
+        "--before",
+        "--author",
+        "--committer",
+        "--grep",
+        "--max-count",
+        "--skip",
+        "--reverse",
+        "--merges",
+        "--no-merges",
+        "--first-parent",
+        "--follow",
+        "--no-renames",
+        "--word-diff",
+        "--check",
+        "--unified",
+        "--raw",
+        "--diff-filter",
+        "--relative",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--summary",
+        "--compact-summary",
+        "--tags",
+        "--heads",
+        "--verify",
+        "--show-current",
+        "--list",
+        "--remotes",
+        "--verbose",
+        "--abbrev-ref",
+        "--symbolic-full-name",
+        "--is-inside-work-tree",
+        "--show-toplevel",
+        "--count",
+        "--line-number",
+        "--files-with-matches",
+        "--ignore-case",
+        "--fixed-strings",
+        "--extended-regexp",
+        "--perl-regexp",
+        "--word-regexp",
+        "--invert-match",
+        "--merged",
+        "--no-merged",
+        "--contains",
+        "--no-contains",
+    }
+)
+
+#: ``git`` config keys that name a program, and the words that make a config file
+#: something other than a list of settings. Any of them in the repository's own
+#: config means ``git`` there can run what the file says.
+_GIT_CONFIG_TRIPWIRES = (
+    "fsmonitor",
+    "external",
+    "textconv",
+    "pager",
+    "sshcommand",
+    "hookspath",
+    "askpass",
+    "program",
+    "helper",
+    "alias",
+    "command",
+    "cmd",
+    "include",
+    "!",
+)
+
+_NUMBER_OPTION = re.compile(r"-\d+[A-Za-z]*$")
+
+
+def is_read_only(command: str, workspace: Path | None = None) -> bool:
+    """Return whether a shell command is recognised as unable to change anything.
+
+    Args:
+        command: The command line exactly as the model asked to run it.
+        workspace: Directory the command runs in. ``git`` needs it, because it is
+            only trusted when the repository's own config names no program to
+            run; without it ``git`` is never read-only.
+
+    Returns:
+        ``True`` only when the whole command is understood and harmless; ``False``
+        for everything else, including every command this module is unsure of.
+    """
+    stages = _split(command)
+    if stages is None:
+        return False
+    return all(_stage_is_read_only(words, workspace) for words in stages)
+
+
+def _split(command: str) -> list[list[str]] | None:
+    """Split a command into pipeline stages of unquoted words, or ``None``.
+
+    This is a scanner, not an interpreter: it walks the string once, tracking
+    whether it is inside quotes, and it gives up the moment it meets anything it
+    would have to *understand* — an operator, an expansion, a control character,
+    a quote that does not close, or a character outside the allowed set.
+    """
+    if not command or len(command) > 4_000 or any(ord(char) < 32 or ord(char) == 127 for char in command):
+        return None
+    stages: list[list[str]] = [[]]
+    word: list[str] | None = None
+    quote = ""
+    index = 0
+    while index < len(command):
+        char = command[index]
+        index += 1
+        if quote == "'":
+            if char == "'":
+                quote = ""
+            else:
+                word.append(char)  # type: ignore[union-attr]
+            continue
+        if quote == '"':
+            if char == '"':
+                quote = ""
+            elif char in _EXPANDING:
+                return None
+            else:
+                word.append(char)  # type: ignore[union-attr]
+            continue
+        if char == " ":
+            if word is not None:
+                stages[-1].append("".join(word))
+                word = None
+        elif char == "|":
+            if index < len(command) and command[index] == "|":
+                return None
+            if word is not None:
+                stages[-1].append("".join(word))
+                word = None
+            if not stages[-1]:
+                return None
+            stages.append([])
+        elif char in "'\"":
+            quote = char
+            if word is None:
+                word = []
+        elif char in _UNQUOTED:
+            if word is None:
+                word = []
+            word.append(char)
+        else:
+            return None
+    if quote:
+        return None
+    if word is not None:
+        stages[-1].append("".join(word))
+    return stages if all(stages) else None
+
+
+def _stage_is_read_only(words: list[str], workspace: Path | None) -> bool:
+    """Judge one pipeline stage: its program, then the arguments that need a look."""
+    # The program word has to *equal* a name on the list, which is the whole check
+    # that `./ls` is not `ls` and `LD_PRELOAD=x ls` is not either: neither is equal
+    # to anything on it, so neither needs a rule of its own.
+    program, args = words[0], words[1:]
+    if program in _PLAIN:
+        return True
+    if program == "find":
+        return _find_is_read_only(args)
+    if program == "rg":
+        return _rg_is_read_only(args)
+    if program == "git":
+        return workspace is not None and _git_is_read_only(args, workspace)
+    return False
+
+
+def _find_is_read_only(args: list[str]) -> bool:
+    """Allow ``find`` when every option it carries is a matching or printing one."""
+    return all(arg in _FIND_OPTIONS or _NUMBER_OPTION.match(arg) for arg in args if arg.startswith("-"))
+
+
+def _rg_is_read_only(args: list[str]) -> bool:
+    """Allow ``rg`` unless an option hands a file to a program."""
+    for arg in args:
+        if arg == "--":
+            break
+        name = arg.split("=", 1)[0]
+        if name in _RG_FORBIDDEN:
+            return False
+        if arg.startswith("-") and not arg.startswith("--") and "z" in arg:
+            return False
+    return True
+
+
+def _git_is_read_only(args: list[str], workspace: Path) -> bool:
+    """Allow a read-only ``git`` subcommand with known-harmless options.
+
+    The subcommand must be the first word: anything before it is a global option
+    such as ``-c`` or ``--exec-path``, which can name a program to run.
+    """
+    if not args or args[0] not in _GIT_SUBCOMMANDS:
+        return False
+    subcommand, rest = args[0], args[1:]
+    options = []
+    for arg in rest:
+        if arg == "--":
+            break
+        if arg.startswith("--"):
+            if arg.split("=", 1)[0] not in _GIT_LONG_OPTIONS:
+                return False
+            options.append(arg.split("=", 1)[0])
+        elif arg.startswith("-") and len(arg) > 1:
+            # ``-O`` hands ``git grep`` a pager to run; every other short option
+            # reads.
+            if "O" in arg:
+                return False
+            options.append(arg)
+    if subcommand == "branch":
+        # A bare name after ``git branch`` creates a branch, so a name is only
+        # a pattern when ``--list`` says it is.
+        positional = [arg for arg in rest if not arg.startswith("-")]
+        if positional and "--list" not in options:
+            return False
+        if any(option in {"-d", "-D", "-m", "-M", "-c", "-C", "-u", "-f", "--force"} for option in options):
+            return False
+    return _git_config_is_inert(workspace)
+
+
+def _git_config_is_inert(workspace: Path) -> bool:
+    """Return whether the repository's own config names no program for git to run.
+
+    The repository is found the way git finds it, by looking in each parent of the
+    workspace in turn, so a shell started in a subdirectory is judged by the config
+    of the repository it is in. A ``.git`` that is a file — a worktree or a
+    submodule — points somewhere this does not follow, and is not inert.
+    """
+    for directory in (workspace, *workspace.parents):
+        git = directory / ".git"
+        try:
+            if git.is_dir():
+                text = (git / "config").read_text(encoding="utf-8", errors="replace").lower()
+                return not any(word in text for word in _GIT_CONFIG_TRIPWIRES)
+            if git.exists():
+                return False
+        except OSError:
+            return False
+    return False