agent-governance 1.0.4__py3-none-any.whl

agent_governance/update_check.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+from packaging.version import InvalidVersion, Version
+
+from agent_governance import PACKAGE_NAME, __version__
+
+try:
+    import tomllib  # type: ignore
+except ModuleNotFoundError:  # pragma: no cover
+    import tomli as tomllib  # type: ignore
+
+DEFAULT_TTL_HOURS = 24
+ERROR_TTL_HOURS = 6
+PYPI_URL = f"https://pypi.org/pypi/{PACKAGE_NAME}/json"
+
+
+@dataclass
+class CacheEntry:
+    checked_at_utc: str
+    installed_version: str
+    latest_version: str
+    source: str
+    etag: str | None = None
+    last_error: str | None = None
+
+
+def resolve_mode(cli_mode: str | None, env: dict[str, str]) -> str:
+    env_mode = env.get("AGENT_UPDATE_CHECK")
+    if env_mode:
+        return env_mode
+    return cli_mode or "auto"
+
+
+def is_ci(env: dict[str, str]) -> bool:
+    return env.get("CI", "").lower() == "true"
+
+
+def parse_time(value: str) -> datetime | None:
+    if not value:
+        return None
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def format_time(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def read_cache(cache_path: Path) -> CacheEntry | None:
+    try:
+        if not cache_path.exists():
+            return None
+        data = json.loads(cache_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    return CacheEntry(
+        checked_at_utc=data.get("checked_at_utc", ""),
+        installed_version=data.get("installed_version", ""),
+        latest_version=data.get("latest_version", ""),
+        source=data.get("source", ""),
+        etag=data.get("etag"),
+        last_error=data.get("last_error"),
+    )
+
+
+def write_cache(cache_path: Path, entry: CacheEntry) -> None:
+    payload = {
+        "checked_at_utc": entry.checked_at_utc,
+        "installed_version": entry.installed_version,
+        "latest_version": entry.latest_version,
+        "source": entry.source,
+        "etag": entry.etag,
+        "last_error": entry.last_error,
+    }
+    try:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        cache_path.write_text(json.dumps(payload, indent=2, sort_keys=True))
+    except OSError:
+        try:
+            fallback = fallback_cache_path()
+            fallback.parent.mkdir(parents=True, exist_ok=True)
+            fallback.write_text(json.dumps(payload, indent=2, sort_keys=True))
+        except OSError:
+            return
+
+
+def get_cache_path(env: dict[str, str]) -> Path:
+    cache_root = env.get("XDG_CACHE_HOME")
+    if cache_root:
+        return Path(cache_root) / "agent_governance" / "update_check.json"
+    return Path.home() / ".cache" / "agent_governance" / "update_check.json"
+
+
+def fallback_cache_path() -> Path:
+    return Path.home() / ".agent_governance" / "cache" / "update_check.json"
+
+
+def should_check(
+    now: datetime,
+    env: dict[str, str],
+    cache: CacheEntry | None,
+    mode: str,
+    ci: bool,
+    interactive: bool,
+) -> tuple[bool, str]:
+    mode = mode or "auto"
+    if mode == "off":
+        return False, "mode off"
+    if mode == "auto":
+        if ci:
+            return False, "ci auto disabled"
+        if not interactive:
+            return False, "non-interactive auto disabled"
+    if mode == "verbose":
+        if ci:
+            return False, "ci verbose disabled"
+        if not interactive:
+            return False, "non-interactive verbose disabled"
+    if mode == "on":
+        return True, "forced on"
+
+    if not cache:
+        return True, "no cache"
+
+    checked_at = parse_time(cache.checked_at_utc)
+    if not checked_at:
+        return True, "cache timestamp invalid"
+
+    installed_version, _source = get_installed_version(env)
+    if cache.installed_version and cache.installed_version != installed_version:
+        return True, "installed version changed"
+
+    ttl_hours = ERROR_TTL_HOURS if cache.last_error else DEFAULT_TTL_HOURS
+    if now - checked_at < timedelta(hours=ttl_hours):
+        return False, "cache fresh"
+    return True, "cache stale"
+
+
+def _source_root_from_env(env: dict[str, str]) -> Path | None:
+    root = env.get("AGENT_GOVERNANCE_ROOT")
+    if root:
+        return Path(root).resolve()
+    for parent in Path(__file__).resolve().parents:
+        if (parent / "pyproject.toml").exists() or (parent / "VERSION").exists():
+            return parent
+    return None
+
+
+def _version_from_pyproject(root: Path) -> str | None:
+    pyproject = root / "pyproject.toml"
+    if not pyproject.exists():
+        return None
+    try:
+        data = tomllib.loads(pyproject.read_text())
+    except tomllib.TOMLDecodeError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    project = data.get("project", {})
+    if isinstance(project, dict):
+        version = project.get("version")
+        if isinstance(version, str) and version.strip():
+            return version.strip()
+    tool = data.get("tool", {})
+    if isinstance(tool, dict):
+        poetry = tool.get("poetry", {})
+        if isinstance(poetry, dict):
+            version = poetry.get("version")
+            if isinstance(version, str) and version.strip():
+                return version.strip()
+    return None
+
+
+def _version_from_source(root: Path) -> str | None:
+    version = _version_from_pyproject(root)
+    if version:
+        return version
+    version_path = root / "VERSION"
+    if version_path.exists():
+        value = version_path.read_text().strip()
+        if value:
+            return value
+    return None
+
+
+def get_installed_version(env: dict[str, str]) -> tuple[str, str]:
+    try:
+        return metadata.version(PACKAGE_NAME), "metadata"
+    except metadata.PackageNotFoundError:
+        root = _source_root_from_env(env)
+        if root:
+            version = _version_from_source(root)
+            if version:
+                return version, "source"
+        return __version__, "unknown"
+
+
+def compare_versions(installed: str, latest: str) -> int:
+    try:
+        installed_v = Version(installed)
+        latest_v = Version(latest)
+    except InvalidVersion:
+        return 0
+    if latest_v.is_prerelease and not installed_v.is_prerelease:
+        return 0
+    if latest_v > installed_v:
+        return 1
+    return 0
+
+
+def fetch_latest(
+    cache: CacheEntry | None, installed_version: str
+) -> tuple[str | None, str | None, str | None]:
+    headers = {
+        "User-Agent": f"{PACKAGE_NAME}/{installed_version}",
+    }
+    if cache and cache.etag:
+        headers["If-None-Match"] = cache.etag
+    req = urllib.request.Request(PYPI_URL, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=2.5) as resp:
+            if resp.status == 304 and cache:
+                return cache.latest_version, cache.etag, None
+            payload = json.loads(resp.read().decode("utf-8"))
+            latest = payload.get("info", {}).get("version")
+            if not isinstance(latest, str):
+                return None, None, "invalid version"
+            etag = resp.headers.get("ETag")
+            return latest, etag, None
+    except urllib.error.HTTPError as exc:
+        if exc.code == 304 and cache:
+            return cache.latest_version, cache.etag, None
+        return None, None, f"http error {exc.code}"
+    except Exception as exc:  # pragma: no cover - network errors
+        return None, None, str(exc)
+
+
+def maybe_check(
+    root: Path,
+    mode: str,
+    env: dict[str, str],
+    policy: str | None,
+    out: Any = sys.stderr,
+) -> None:
+    if policy == "off":
+        if mode == "verbose":
+            out.write("update check disabled by policy\n")
+        return
+
+    now = datetime.now(timezone.utc)
+    cache_path = get_cache_path(env)
+    cache = read_cache(cache_path)
+    ci = is_ci(env)
+    interactive = sys.stderr.isatty()
+    should_run, reason = should_check(now, env, cache, mode, ci, interactive)
+    if not should_run:
+        if mode == "verbose":
+            out.write(f"update check skipped: {reason}\n")
+        return
+
+    installed_version, _source = get_installed_version(env)
+    latest, etag, error = fetch_latest(cache, installed_version)
+    if error or not latest:
+        entry = CacheEntry(
+            checked_at_utc=format_time(now),
+            installed_version=installed_version,
+            latest_version=cache.latest_version if cache else "",
+            source="pypi",
+            etag=etag or (cache.etag if cache else None),
+            last_error=error or "unknown error",
+        )
+        write_cache(cache_path, entry)
+        if mode == "verbose":
+            out.write(f"update check failed: {entry.last_error}\n")
+        return
+
+    entry = CacheEntry(
+        checked_at_utc=format_time(now),
+        installed_version=installed_version,
+        latest_version=latest,
+        source="pypi",
+        etag=etag,
+        last_error=None,
+    )
+    write_cache(cache_path, entry)
+
+    if compare_versions(installed_version, latest) > 0:
+        out.write(
+            f"{PACKAGE_NAME} update available: installed {installed_version}, "
+            f"latest {latest} (source: pypi).\n"
+        )

agent_governance-1.0.4.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: agent-governance
+Version: 1.0.4
+Summary: Agent governance tooling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: packaging>=22
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+
+# Bounded Agent Framework
+
+This repository defines a **repo-local, enforceable framework** for using AI sub-agents as bounded workers.
+
+This is **not** an application.
+This is **not** an orchestration service.
+This is **not** an autonomy experiment.
+
+This is infrastructure.
+
+---
+
+## What this system is
+
+- Agents are **roles defined in Markdown**
+- Agents are **instantiated per model call**
+- Nothing is persistent
+- Nothing runs automatically
+- Nothing is trusted without artifacts
+
+The framework exists to:
+
+- force correct task decomposition
+- prevent scope creep
+- require evidence for completion
+- make agent behavior reproducible and auditable
+
+---
+
+## Core invariants
+
+1. **Repo-local**
+   - All agent rules, schemas, and tools live in the repo
+   - No systemwide installs
+   - No hidden dependencies
+
+2. **Separation of concerns**
+   - Agent roles (Markdown) change frequently
+   - Schemas change occasionally
+   - Tooling changes rarely
+
+3. **Artifacts over prose**
+   - Diffs, logs, commands, tests are required
+   - Narrative text is secondary
+
+4. **Orchestrator ≠ implementer**
+   - Orchestrator plans and validates
+   - Workers produce changes
+   - Single-writer rule per scope
+
+5. **No schema, no run**
+   - Tasks and outputs must validate
+   - Invalid packets are rejected
+
+---
+
+## Repository layout (expected)
+
+agents/
+roles/
+contracts/
+checklists/
+tools/
+logs/
+reports/
+adr/
+
+---
+
+## Usage summary
+
+1. Create a task packet (YAML)
+2. Validate it against schema
+3. Run the agent with role + task
+4. Collect output packet + artifacts
+5. Validate output
+6. Gate before merge
+
+Tooling baseline: use `agent-governance>=1.0.4`.
+
+## Repo introspection
+
+`agentctl init` scans the current repo to generate a policy overlay plus an
+evidence-backed report. It never edits repo files unless `--write` is set, and
+it never calls an LLM.
+
+## Bootstrap policy block
+
+Use `agentctl bootstrap` to author or update the AGENTS.md policy block from the
+canonical role registry. It is preview-only unless `--write` is provided.
+
+What it never does:
+
+- no network access
+- no repo mutation (except writing the three outputs when `--write` is set)
+- no heuristic guesses without a cited file + line range
+
+Outputs (when `--write`):
+
+- `.agents/generated/AGENTS.repo.overlay.yaml`
+- `.agents/generated/init_report.md`
+- `.agents/generated/init_facts.json`
+
+At runtime, the orchestrator merges the overlay with the base policy to add
+repo-specific verify commands and risk paths before dispatching work. This lets
+one global role set adapt to local tooling without changing the core policy.
+
+Deterministic + auditable:
+
+- each detected fact includes a source file and line range
+- output ordering is stable for diff-friendly review
+- dry-runs show planned writes without touching disk
+
+## Update checks
+
+The CLI can optionally warn if a newer `agent_governance` version exists.
+Defaults: once per 24h, skipped in CI, and never blocks command execution.
+
+Disable with `--update-check=off` or `AGENT_UPDATE_CHECK=off`. Repos may set
+`update_check: off` in `agents/repo_profile.yaml` to fully disable network use.
+
+This system replaces trust with structure.

agent_governance-1.0.4.dist-info/RECORD

@@ -0,0 +1,12 @@
+agent_governance/__init__.py,sha256=gVJvP56TC_hU6GYFMwuQE4vys120FBs21LzyBkFvhFY,1494
+agent_governance/agentctl.py,sha256=7ouKYGek4GiHGCGkm_ghChosTR7mt1PFe4RMPw1Q8XQ,30982
+agent_governance/init.py,sha256=6yGQZ9OUhbwI6RgTezj-d0Ku0s0EBm6xbF5WXDlIVLQ,34127
+agent_governance/update_check.py,sha256=R-pudcL5RThA0V01-CqIJiQnXK6KZVVB8K80-ti7WuQ,9453
+agent_governance/contracts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_governance/contracts/output_packet.schema.json,sha256=zAwfreDQm5vmLvAdLcVr8uC_HOnRMU_M5Ji6AyemjRo,2088
+agent_governance/contracts/task_packet.schema.json,sha256=4zUqV3QUUbV0zpyOpZV_1vZE-zNamyFxPs8KH2gQpg4,1664
+agent_governance-1.0.4.dist-info/METADATA,sha256=IFx6V3Ghnkn8jkuITIquF6KmpO6m18ZH2nmfSsgtPnE,3448
+agent_governance-1.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+agent_governance-1.0.4.dist-info/entry_points.txt,sha256=iSbWaXVz3_Sc0TDsgpgAA3qh7Jk5qSmxVfaBuQJTnvs,60
+agent_governance-1.0.4.dist-info/top_level.txt,sha256=s1hxHyuJLAc3on5R5N8JCE0kI5z8_vMYKTTAWiax1eQ,17
+agent_governance-1.0.4.dist-info/RECORD,,

agent_governance-1.0.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_governance-1.0.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentctl = agent_governance.agentctl:main

agent_governance-1.0.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_governance