agent-safe-runner 0.4.0__py3-none-any.whl

agent_safe_runner/__init__.py

@@ -0,0 +1,3 @@
+"""Safe, auditable local job execution for AI-agent workflows."""
+
+__version__ = "0.4.0"

agent_safe_runner/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_safe_runner/audit.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import threading
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .errors import AuditIntegrityError
+from .redaction import redact
+
+
+@contextmanager
+def _file_lock(path: Path):
+    """Use a one-byte advisory lock on Windows and flock on POSIX."""
+    lock_path = Path(f"{path}.lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+b") as handle:
+        handle.seek(0, os.SEEK_END)
+        if handle.tell() == 0:
+            handle.write(b"0")
+            handle.flush()
+        handle.seek(0)
+        if os.name == "nt":
+            import msvcrt
+
+            msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+            try:
+                yield
+            finally:
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+class AuditLog:
+    """Append-only JSONL audit log with a hash chain for accidental tamper detection."""
+
+    _registry_lock = threading.Lock()
+    _path_locks: dict[str, threading.Lock] = {}
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        lock_key = str(self.path.resolve(strict=False)).casefold()
+        with self._registry_lock:
+            self._lock = self._path_locks.setdefault(lock_key, threading.Lock())
+
+    @staticmethod
+    def _digest(record: dict[str, Any]) -> str:
+        encoded = json.dumps(record, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+        return hashlib.sha256(encoded).hexdigest()
+
+    def _tail(self) -> tuple[int, str | None]:
+        if not self.path.exists():
+            return 0, None
+        last = None
+        with self.path.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                if line.strip():
+                    last = line
+        if last is None:
+            return 0, None
+        try:
+            record = json.loads(last)
+            return int(record["seq"]), str(record["hash"])
+        except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+            raise AuditIntegrityError("cannot append to an invalid audit log") from exc
+
+    def append(self, event: str, **data: object) -> dict[str, Any]:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self._lock:
+            with _file_lock(self.path):
+                sequence, previous_hash = self._tail()
+                record: dict[str, Any] = {
+                    "seq": sequence + 1,
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
+                    "event": event,
+                    "prev_hash": previous_hash,
+                    "data": redact(data),
+                }
+                record["hash"] = self._digest(record)
+                descriptor = os.open(self.path, os.O_APPEND | os.O_CREAT | os.O_WRONLY, 0o600)
+                try:
+                    payload = (json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n").encode("utf-8")
+                    os.write(descriptor, payload)
+                    os.fsync(descriptor)
+                finally:
+                    os.close(descriptor)
+                return record
+
+    def verify(self) -> dict[str, int | bool]:
+        expected_sequence = 1
+        previous_hash = None
+        entries = 0
+        if not self.path.exists():
+            return {"valid": True, "entries": 0}
+        with self._lock:
+            with _file_lock(self.path):
+                with self.path.open("r", encoding="utf-8") as handle:
+                    for line_number, line in enumerate(handle, start=1):
+                        if not line.strip():
+                            continue
+                        try:
+                            record = json.loads(line)
+                            actual_hash = record.pop("hash")
+                        except (KeyError, json.JSONDecodeError) as exc:
+                            raise AuditIntegrityError(f"invalid audit entry at line {line_number}") from exc
+                        if record.get("seq") != expected_sequence or record.get("prev_hash") != previous_hash:
+                            raise AuditIntegrityError(f"broken audit chain at line {line_number}")
+                        calculated_hash = self._digest(record)
+                        if actual_hash != calculated_hash:
+                            raise AuditIntegrityError(f"audit hash mismatch at line {line_number}")
+                        previous_hash = actual_hash
+                        expected_sequence += 1
+                        entries += 1
+        return {"valid": True, "entries": entries}

agent_safe_runner/cli.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+from . import __version__
+from .audit import AuditLog
+from .core import APPROVAL_STATUSES, JobStore
+from .errors import RunnerError
+from .policy import Policy
+
+
+STATUSES = ("queued", "running", "retry_wait", "succeeded", "failed", "cancelled", "dead_letter")
+
+
+def _emit(payload: Any, *, error: bool = False) -> None:
+    stream = sys.stderr if error else sys.stdout
+    print(json.dumps(payload, ensure_ascii=False, sort_keys=True), file=stream)
+
+
+def _command(parts: Sequence[str]) -> tuple[str, ...]:
+    values = list(parts)
+    if values and values[0] == "--":
+        values.pop(0)
+    if not values:
+        raise ValueError("a command is required after --")
+    return tuple(values)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agent-safe", description="Local-first, policy-gated job runner")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--db", default="agent-safe.sqlite3", help="SQLite queue path")
+    parser.add_argument("--audit", default="audit.jsonl", help="JSONL audit path")
+    parser.add_argument("--policy", default="agent-safe-policy.json", help="Policy JSON path")
+    sub = parser.add_subparsers(dest="action", required=True)
+
+    init_policy = sub.add_parser("init-policy", help="Write a conservative sample policy")
+    init_policy.add_argument("path", nargs="?", default="agent-safe-policy.json")
+
+    submit = sub.add_parser("submit", help="Queue a command without executing it")
+    submit.add_argument("--key")
+    submit.add_argument("--cwd")
+    submit.add_argument("--timeout", type=int, default=60)
+    submit.add_argument("--max-attempts", type=int, default=1)
+    submit.add_argument("command", nargs=argparse.REMAINDER, help="Use: submit [options] -- program arg...")
+
+    listing = sub.add_parser("list", help="List jobs")
+    listing.add_argument("--status", action="append", choices=STATUSES, default=[])
+    listing.add_argument("--limit", type=int, default=100)
+    listing.add_argument("--approval", choices=APPROVAL_STATUSES)
+
+    inbox = sub.add_parser("inbox", help="List pending jobs awaiting an operator decision")
+    inbox.add_argument("--limit", type=int, default=100)
+
+    assess = sub.add_parser("assess", help="Report policy allowance without approving or executing")
+    assess.add_argument("job_id")
+
+    approve = sub.add_parser("approve", help="Approve a pending job that also passes policy")
+    approve.add_argument("job_id")
+    approve.add_argument("--by", required=True, help="Operator label, not authentication")
+    approve.add_argument("--reason")
+
+    deny = sub.add_parser("deny", help="Deny and cancel a pending job")
+    deny.add_argument("job_id")
+    deny.add_argument("--by", required=True, help="Operator label, not authentication")
+    deny.add_argument("--reason", required=True)
+
+    show = sub.add_parser("show", help="Show one job")
+    show.add_argument("job_id")
+
+    run = sub.add_parser("run", help="Dry-run a job; --execute requires approval and policy allowance")
+    run.add_argument("job_id")
+    run.add_argument("--execute", action="store_true")
+    run.add_argument("--worker", default="direct")
+
+    work = sub.add_parser("work", help="Process at most one available job")
+    work.add_argument("--once", action="store_true", required=True)
+    work.add_argument("--execute", action="store_true")
+    work.add_argument("--worker", default="worker")
+
+    cancel = sub.add_parser("cancel", help="Cancel a queued job")
+    cancel.add_argument("job_id")
+
+    retry = sub.add_parser("retry", help="Reset failed, cancelled, or dead-letter jobs to pending approval")
+    retry.add_argument("job_id")
+
+    sub.add_parser("audit-verify", help="Verify the JSONL audit hash chain")
+    sub.add_parser("mcp", help="Serve proposal/read-only MCP over stdio; requires absolute global paths and [mcp]")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.action == "init-policy":
+            destination = Path(args.path)
+            if destination.exists():
+                raise ValueError(f"policy already exists: {destination}")
+            destination.write_text(json.dumps(Policy.sample(), indent=2) + "\n", encoding="utf-8")
+            _emit({"status": "created", "path": str(destination.resolve())})
+            return 0
+        if args.action == "audit-verify":
+            _emit(AuditLog(args.audit).verify())
+            return 0
+        if args.action == "mcp":
+            from .mcp_server import serve
+
+            serve(args.db, args.audit, args.policy)
+            return 0
+
+        policy = Policy.from_file(args.policy)
+        with JobStore(args.db, args.audit, policy=policy) as store:
+            if args.action == "submit":
+                job = store.submit(
+                    _command(args.command),
+                    args.key,
+                    cwd=args.cwd,
+                    timeout=args.timeout,
+                    max_attempts=args.max_attempts,
+                )
+                _emit(job.to_dict())
+            elif args.action == "list":
+                _emit([job.to_dict() for job in store.list(tuple(args.status), args.limit, approval=args.approval)])
+            elif args.action == "inbox":
+                _emit([job.to_dict() for job in store.inbox(args.limit)])
+            elif args.action == "assess":
+                _emit(store.assess(args.job_id))
+            elif args.action == "approve":
+                _emit(store.approve(args.job_id, by=args.by, reason=args.reason).to_dict())
+            elif args.action == "deny":
+                _emit(store.deny(args.job_id, by=args.by, reason=args.reason).to_dict())
+            elif args.action == "show":
+                _emit(store.get(args.job_id).to_dict())
+            elif args.action == "run":
+                _emit(store.run(args.job_id, execute=args.execute, worker_id=args.worker).to_dict())
+            elif args.action == "work":
+                job = store.work_once(execute=args.execute, worker_id=args.worker)
+                _emit({"status": "idle"} if job is None else job.to_dict())
+            elif args.action == "cancel":
+                _emit(store.cancel(args.job_id).to_dict())
+            elif args.action == "retry":
+                _emit(store.retry(args.job_id).to_dict())
+        return 0
+    except (RunnerError, ValueError, OSError) as exc:
+        code = getattr(exc, "code", "invalid_input")
+        _emit({"error": {"code": code, "message": str(exc)}}, error=True)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())