agentic-runner 2.6.0__py3-none-any.whl

agentic_runner/host_store.py

@@ -0,0 +1,295 @@
+"""The workstation's Credential Reference store (PRD issue 47, map ticket 23 item 5).
+
+The OS credential store when it is reachable -- Keychain on macOS, Secret Service on
+Linux, Credential Manager on Windows -- and a directory of ``0600`` files under the
+state directory otherwise. Reachable is the operative word: a login agent reaches the
+login keychain and a daemon does not (Apple TN3137), which is half the reason the
+workstation Runner is a login agent at all.
+
+Every backend is driven through the OS's own tool or API rather than a Python keyring
+library: ``security`` and ``secret-tool`` ship with the OS (or its desktop), and the
+Runner stays inside the dependency set an Organisation already audited. Values reach the
+tools on **stdin**, never argv, because argv is readable by every process on the box.
+
+The store holds a value per Credential Reference name, scoped by Organisation -- one
+process per Organisation (23 item 3) means one service name per process. The Runner
+itself only ever *reads* (``credentials.HostCredentialStore``); ``put`` is the host
+operator's act, through ``agentic-runner credential set``.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Protocol
+
+from agentic_runner.credentials import DirectoryCredentialStore
+from agentic_runner_contracts.runner_registration import StoreKind
+
+__all__ = [
+    "FileCredentialStore",
+    "KeychainStore",
+    "SecretServiceStore",
+    "WindowsCredentialStore",
+    "WorkstationStore",
+    "open_workstation_store",
+]
+
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+
+
+class WorkstationStore(Protocol):
+    kind: StoreKind
+
+    def get(self, reference: str) -> str | None: ...
+    def put(self, reference: str, value: str) -> None: ...
+
+
+def _single_segment(reference: str) -> str:
+    # The same rule `DirectoryCredentialStore` enforces, so a reference that works in one
+    # store works in every other.
+    if not reference or "/" in reference or "\\" in reference or reference in {".", ".."}:
+        raise ValueError(f"Credential Reference {reference!r} is not a single name")
+    return reference
+
+
+class FileCredentialStore(DirectoryCredentialStore):
+    """The fallback: one ``0600`` file per reference, in a ``0700`` directory."""
+
+    kind = StoreKind.FILE
+
+    def __init__(self, root: Path) -> None:
+        super().__init__(root)
+        self.root = root
+
+    def put(self, reference: str, value: str) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.root.chmod(0o700)
+        path = self.root / _single_segment(reference)
+        # Created 0600 rather than chmod-ed after: there is no instant at which the value
+        # sits in a file another uid can open.
+        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(value)
+        path.chmod(0o600)
+
+
+class KeychainStore:
+    """macOS: generic passwords in the login keychain, via ``security``."""
+
+    kind = StoreKind.KEYCHAIN
+
+    def __init__(
+        self, service: str, *, keychain: Path | None = None, run: Runner = subprocess.run
+    ) -> None:
+        self._service = service
+        self._keychain = [str(keychain)] if keychain is not None else []
+        self._run = run
+
+    def available(self) -> bool:
+        if shutil.which("security") is None:
+            return False
+        probe = self._run(
+            ["security", "show-keychain-info", *self._keychain],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return probe.returncode == 0
+
+    def get(self, reference: str) -> str | None:
+        found = self._run(
+            [
+                "security",
+                "find-generic-password",
+                "-s",
+                self._service,
+                "-a",
+                _single_segment(reference),
+                "-w",
+                *self._keychain,
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return found.stdout.rstrip("\n") if found.returncode == 0 else None
+
+    def put(self, reference: str, value: str) -> None:
+        if "\n" in value:
+            raise ValueError("a Keychain value is a single line")
+        # `security -i` reads its command from stdin, so the value never enters argv.
+        command = " ".join(
+            [
+                "add-generic-password -U",
+                f"-s {_quote(self._service)}",
+                f"-a {_quote(_single_segment(reference))}",
+                f"-w {_quote(value)}",
+                *(_quote(item) for item in self._keychain),
+            ]
+        )
+        stored = self._run(
+            ["security", "-i"], input=command + "\n", capture_output=True, text=True, check=False
+        )
+        if stored.returncode != 0 or stored.stderr.strip():
+            raise RuntimeError(f"Keychain refused the value: {stored.stderr.strip()}")
+
+
+def _quote(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+class SecretServiceStore:
+    """Linux: the desktop's Secret Service (GNOME Keyring, KWallet), via ``secret-tool``."""
+
+    kind = StoreKind.SECRET_SERVICE
+
+    def __init__(self, service: str, *, run: Runner = subprocess.run) -> None:
+        self._service = service
+        self._run = run
+
+    def available(self) -> bool:
+        if shutil.which("secret-tool") is None:
+            return False
+        # A lookup that finds nothing exits 1 with nothing on stderr; one that cannot
+        # reach the bus (a headless box, a daemon) says so on stderr.
+        probe = self._run(
+            ["secret-tool", "lookup", "service", self._service, "account", "-probe-"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return probe.returncode == 0 or not probe.stderr.strip()
+
+    def get(self, reference: str) -> str | None:
+        found = self._run(
+            ["secret-tool", "lookup", *self._attributes(reference)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return found.stdout if found.returncode == 0 and found.stdout else None
+
+    def put(self, reference: str, value: str) -> None:
+        stored = self._run(
+            [
+                "secret-tool",
+                "store",
+                f"--label=agentic-runner {self._service} {reference}",
+                *self._attributes(reference),
+            ],
+            input=value,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if stored.returncode != 0:
+            raise RuntimeError(f"Secret Service refused the value: {stored.stderr.strip()}")
+
+    def _attributes(self, reference: str) -> Sequence[str]:
+        return ["service", self._service, "account", _single_segment(reference)]
+
+
+class WindowsCredentialStore:
+    """Windows: generic credentials in the user's Credential Manager (``CredReadW``)."""
+
+    kind = StoreKind.CREDENTIAL_MANAGER
+
+    def __init__(self, service: str) -> None:
+        self._service = service
+
+    def available(self) -> bool:
+        return sys.platform == "win32"
+
+    def _target(self, reference: str) -> str:
+        return f"{self._service}/{_single_segment(reference)}"
+
+    def get(self, reference: str) -> str | None:
+        if sys.platform != "win32":
+            return None
+        return _win_read(self._target(reference))
+
+    def put(self, reference: str, value: str) -> None:
+        if sys.platform != "win32":
+            raise RuntimeError("Credential Manager exists only on Windows")
+        _win_write(self._target(reference), value)
+
+
+if sys.platform == "win32":  # pragma: no cover - exercised on Windows only
+    import ctypes
+    from ctypes import wintypes
+
+    _CRED_TYPE_GENERIC = 1
+    _CRED_PERSIST_LOCAL_MACHINE = 2
+
+    class _Credential(ctypes.Structure):
+        _fields_ = [
+            ("Flags", wintypes.DWORD),
+            ("Type", wintypes.DWORD),
+            ("TargetName", wintypes.LPWSTR),
+            ("Comment", wintypes.LPWSTR),
+            ("LastWritten", wintypes.FILETIME),
+            ("CredentialBlobSize", wintypes.DWORD),
+            ("CredentialBlob", ctypes.POINTER(ctypes.c_char)),
+            ("Persist", wintypes.DWORD),
+            ("AttributeCount", wintypes.DWORD),
+            ("Attributes", ctypes.c_void_p),
+            ("TargetAlias", wintypes.LPWSTR),
+            ("UserName", wintypes.LPWSTR),
+        ]
+
+    _advapi = ctypes.WinDLL("advapi32", use_last_error=True)
+
+    def _win_read(target: str) -> str | None:
+        pointer = ctypes.POINTER(_Credential)()
+        if not _advapi.CredReadW(target, _CRED_TYPE_GENERIC, 0, ctypes.byref(pointer)):
+            return None
+        try:
+            credential = pointer.contents
+            blob = ctypes.string_at(credential.CredentialBlob, credential.CredentialBlobSize)
+            return blob.decode("utf-8")
+        finally:
+            _advapi.CredFree(pointer)
+
+    def _win_write(target: str, value: str) -> None:
+        blob = value.encode("utf-8")
+        credential = _Credential()
+        credential.Type = _CRED_TYPE_GENERIC
+        credential.TargetName = target
+        credential.CredentialBlobSize = len(blob)
+        credential.CredentialBlob = ctypes.cast(
+            ctypes.create_string_buffer(blob, len(blob)), ctypes.POINTER(ctypes.c_char)
+        )
+        credential.Persist = _CRED_PERSIST_LOCAL_MACHINE
+        credential.UserName = "agentic-runner"
+        if not _advapi.CredWriteW(ctypes.byref(credential), 0):
+            raise ctypes.WinError(ctypes.get_last_error())
+
+else:
+
+    def _win_read(target: str) -> str | None:
+        return None
+
+    def _win_write(target: str, value: str) -> None:
+        raise RuntimeError("Credential Manager exists only on Windows")
+
+
+def open_workstation_store(
+    org: str, *, fallback: Path, platform: str = sys.platform, run: Runner = subprocess.run
+) -> WorkstationStore:
+    """The OS store for this platform if it answers, else the ``0600`` file fallback."""
+
+    service = f"agentic-runner.{org}"
+    candidates: dict[str, KeychainStore | SecretServiceStore | WindowsCredentialStore] = {
+        "darwin": KeychainStore(service, run=run),
+        "linux": SecretServiceStore(service, run=run),
+        "win32": WindowsCredentialStore(service),
+    }
+    candidate = candidates.get(platform)
+    if candidate is not None and candidate.available():
+        return candidate
+    return FileCredentialStore(fallback)

agentic_runner/integrations/git/__init__.py

@@ -0,0 +1 @@
+"""Git workspace contracts and deterministic test adapters."""

agentic_runner/integrations/git/contracts.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from agentic_runner.integrations.git.evidence import GitEvidence
+
+DEFAULT_COMMIT_AUTHOR_NAME = "QTS Agentic OS"
+DEFAULT_COMMIT_AUTHOR_EMAIL = "agentic-os[bot]@qts.one"
+
+
+@dataclass(frozen=True)
+class CloneWorkspaceRequest:
+    """Request to clone a tokenless remote into a worker-local workspace path."""
+
+    repo_full_name: str
+    remote_url: str
+    workspace_root: Path
+    workspace_path: Path
+
+
+@dataclass(frozen=True)
+class CloneWorkspaceResult:
+    """Result of preparing a local repository workspace."""
+
+    repo_full_name: str
+    remote_url: str
+    workspace_root: Path
+    workspace_path: Path
+
+
+@dataclass(frozen=True)
+class AdoptWorkspaceRequest:
+    """A checkout produced outside this adapter, offered for adoption."""
+
+    repo_full_name: str
+    remote_url: str
+    workspace_root: Path
+    workspace_path: Path
+    work_branch: str
+
+
+@dataclass(frozen=True)
+class FetchBranchRequest:
+    """Request to fetch a base branch into an existing workspace."""
+
+    repo_full_name: str
+    workspace_path: Path
+    base_branch: str
+
+
+@dataclass(frozen=True)
+class FetchBranchResult:
+    """Result of fetching a base branch."""
+
+    repo_full_name: str
+    workspace_path: Path
+    base_branch: str
+
+
+@dataclass(frozen=True)
+class CheckoutWorkBranchRequest:
+    """Request to create or reset a generated work branch from the base branch."""
+
+    repo_full_name: str
+    workspace_path: Path
+    base_branch: str
+    work_branch: str
+
+
+@dataclass(frozen=True)
+class CheckoutWorkBranchResult:
+    """Result of checking out a generated work branch."""
+
+    repo_full_name: str
+    workspace_path: Path
+    base_branch: str
+    work_branch: str
+
+
+@dataclass(frozen=True)
+class CommitAllRequest:
+    """Request to commit all workspace changes with a deterministic author."""
+
+    repo_full_name: str
+    workspace_path: Path
+    work_branch: str
+    commit_message: str
+    author_name: str = DEFAULT_COMMIT_AUTHOR_NAME
+    author_email: str = DEFAULT_COMMIT_AUTHOR_EMAIL
+
+
+@dataclass(frozen=True)
+class CommitAllResult:
+    """Result of committing all workspace changes."""
+
+    repo_full_name: str
+    workspace_path: Path
+    work_branch: str
+    commit_message: str
+    author_name: str
+    author_email: str
+    commit_id: str
+
+
+@dataclass(frozen=True)
+class PushBranchRequest:
+    """Request to push the current HEAD to a generated work branch."""
+
+    repo_full_name: str
+    workspace_path: Path
+    base_branch: str
+    work_branch: str
+    protected_branches: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class PushBranchResult:
+    """Result of pushing a generated work branch."""
+
+    repo_full_name: str
+    workspace_path: Path
+    work_branch: str
+    refspec: str
+    commit_id: str
+
+
+@dataclass(frozen=True)
+class PrepareVerifierWorkspaceRequest:
+    """Request to attest a verifier workspace at the approved generated branch head."""
+
+    repo_full_name: str
+    workspace_root: Path
+    workspace_path: Path
+    work_branch: str
+    approved_head_sha: str
+
+
+@dataclass(frozen=True)
+class PrepareVerifierWorkspaceResult:
+    """Attestation proving the verifier workspace path, HEAD, and status."""
+
+    repo_full_name: str
+    workspace_root: Path
+    workspace_path: Path
+    work_branch: str
+    approved_head_sha: str
+    attested_head_sha: str
+    status_summary: str
+
+
+@runtime_checkable
+class GitWorkspace(Protocol):
+    """Deep seam for local git workspace lifecycle operations."""
+
+    def clone_repository(self, request: CloneWorkspaceRequest) -> CloneWorkspaceResult:
+        """Clone a tokenless remote into a worker-local workspace."""
+
+    def adopt_existing_clone(self, request: AdoptWorkspaceRequest) -> CloneWorkspaceResult:
+        """Adopt a checkout this adapter did not clone (the ``checkout`` hook, issue 45).
+
+        Every other method here is keyed on a workspace this adapter cloned itself, so a
+        ``checkout`` Runner Hook -- a separate process, which cannot reach the adapter --
+        has to hand its result back across the port or the Directive dies on the first
+        git call after it. Validated rather than trusted: a work tree root, ``origin`` at
+        the repository's own remote (the push refspec goes there), and the work branch
+        already checked out.
+        """
+
+    def fetch_base_branch(self, request: FetchBranchRequest) -> FetchBranchResult:
+        """Fetch the requested base branch into a workspace."""
+
+    def checkout_work_branch(
+        self,
+        request: CheckoutWorkBranchRequest,
+    ) -> CheckoutWorkBranchResult:
+        """Checkout a generated work branch from the base branch."""
+
+    def commit_all(self, request: CommitAllRequest) -> CommitAllResult:
+        """Commit all workspace changes."""
+
+    def push_branch(self, request: PushBranchRequest) -> PushBranchResult:
+        """Push the work branch using a safe HEAD-to-branch refspec."""
+
+    def prepare_verifier_workspace(
+        self,
+        request: PrepareVerifierWorkspaceRequest,
+    ) -> PrepareVerifierWorkspaceResult:
+        """Prepare and attest a clean verifier workspace at the approved head."""
+
+    def collect_git_evidence(
+        self,
+        workspace_path: Path,
+        output_limit_bytes: int | None = None,
+    ) -> GitEvidence:
+        """Collect bounded, redacted status and diff evidence for a workspace."""