cardinal-agent-core 0.3.0__py3-none-any.whl

cardinal_agent_core-0.3.0.dist-info/METADATA

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: cardinal-agent-core
+Version: 0.3.0
+Summary: The Cardinal agent-telemetry contract: OTLP emission, initiative resolution, spend-limits delivery, device-code consent.
+Author-email: CardinalHQ <support@cardinalhq.io>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/cardinalhq/cardinal-agent-plugins
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# cardinal-agent-core
+
+The Cardinal agent-telemetry contract, written once. See
+`../docs/specs/agent-core.md` for the extraction spec and
+`../README.md` for the monorepo layout.
+
+Ships two ways:
+
+- **Vendored** into each CLI plugin artifact at build time
+  (`build/vendor.py`) — plugins stay self-contained, no pip.
+- **Installed** as a normal package (`pip install -e core/`) by
+  server-side consumers (the omnigent adapter) and the test suite.
+
+```bash
+cd core && python3 -m unittest discover tests -v
+```

cardinal_agent_core-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cardinal_core/__init__.py,sha256=-uhjC9IopPFu0ORTxg-7QNywtPKf7UpN0AxxcmV7WQI,623
+cardinal_core/bashclass.py,sha256=NfG6MKWfGRBVm2vaj-Rfx48QVDrcq9BlbGYhl28dud0,5492
+cardinal_core/deviceflow.py,sha256=w6EG1CloK5yFq83JLn0CIF4ZoA7bmeDvs_PfReAlZ1c,6688
+cardinal_core/initiative.py,sha256=yhM8S5EiA2TvJoG7AwEVjWRwfRdPVXdDv9nKg3O7sWE,4175
+cardinal_core/limits.py,sha256=b-w5GfCZjc-S-RdY0kJRdeAIaSjti8MYQ31Nlw31z9E,12739
+cardinal_core/otlp.py,sha256=c2IPrcTT-7Gon6jMXxqJ1KwJf26mNxeI-aUu9lDavvs,6313
+cardinal_core/paths.py,sha256=Rjr8KbXw-S_s5utqmDUl6OtkMPtMcHzieHfidwpaLVo,4500
+cardinal_core/pricing.py,sha256=HXm_XiRvyabVv7hcbjOajEIP5GqdAh_5pUD3XyNq8XE,6575
+cardinal_core/session.py,sha256=blgkrlC_nu9s9da7rCIpTqxy9CrWQF_cokFtCJpdw38,6746
+cardinal_agent_core-0.3.0.dist-info/METADATA,sha256=UdPiVz4igRX8QGu6o1LzoMj0E6ALvtSzHipmU5-HvkA,914
+cardinal_agent_core-0.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+cardinal_agent_core-0.3.0.dist-info/top_level.txt,sha256=_iORClBRzXHjbhqhLs3zLr26UGxKYGudDNy4XlHjvGw,14
+cardinal_agent_core-0.3.0.dist-info/RECORD,,

cardinal_agent_core-0.3.0.dist-info/WHEEL

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

cardinal_agent_core-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cardinal_core

cardinal_core/__init__.py

@@ -0,0 +1,14 @@
+"""cardinal-agent-core — the Cardinal agent-telemetry contract, written once.
+
+Extracted from the four per-agent plugins (claude/codex/cursor/gemini) per
+docs/specs/agent-core.md. Adapters supply agent-specific facts (paths,
+event names, payload spellings); this package owns the algorithms and the
+OTLP contract.
+
+Design constraints honored throughout (spec §omnigent constraints):
+- No module-level path constants — state locations come in via AgentPaths.
+- No module-level connection state — emit targets are arguments.
+- Identity (user_email/actor) is an argument, never a file read.
+"""
+
+CORE_VERSION = "0.3.0"

cardinal_core/bashclass.py

@@ -0,0 +1,140 @@
+"""Bash verb classification — a closed enum derived from the command WORD
+only; the command string is never emitted on cardinal.turn_tool, in whole
+or in part. Ambiguity resolves toward the write-risky side (the harvester
+discounts write work, so misclassifying read-as-write only costs savings
+estimate, never privacy or correctness).
+
+This is the single copy; per-plugin fixture parity is enforced by the
+cross-adapter contract test (spec §Test strategy).
+
+Write-risk ordering: when a compound command spans classes, the
+lowest-index class wins and bash_multi=true is emitted.
+"""
+
+from __future__ import annotations
+
+BASH_CLASS_RANK = (
+    "file-write",
+    "git-write",
+    "pkg",
+    "network",
+    "build",
+    "test",
+    "git-read",
+    "file-read",
+    "other",
+)
+
+# Single-word command → class. Unknown words → "other".
+BASH_CMD_CLASS = {
+    # test
+    "pytest": "test", "tox": "test", "jest": "test", "vitest": "test",
+    "rspec": "test", "phpunit": "test",
+    # build
+    "make": "build", "cmake": "build", "tsc": "build", "gradle": "build",
+    "mvn": "build", "gcc": "build", "clang": "build", "webpack": "build",
+    # pkg
+    "pip": "pkg", "pip3": "pkg", "brew": "pkg", "gem": "pkg",
+    "apt": "pkg", "apt-get": "pkg", "yum": "pkg", "dnf": "pkg",
+    "apk": "pkg", "poetry": "pkg", "uv": "pkg",
+    # file-read
+    "ls": "file-read", "cat": "file-read", "find": "file-read",
+    "grep": "file-read", "rg": "file-read", "head": "file-read",
+    "tail": "file-read", "wc": "file-read", "du": "file-read",
+    "df": "file-read", "stat": "file-read", "file": "file-read",
+    "tree": "file-read", "which": "file-read", "pwd": "file-read",
+    "less": "file-read", "more": "file-read", "diff": "file-read",
+    "awk": "file-read", "echo": "file-read", "sort": "file-read",
+    "uniq": "file-read", "cut": "file-read", "jq": "file-read",
+    # file-write (sed classifies here: -i vs not is an argument, and
+    # arguments are never consulted — write-risky wins)
+    "rm": "file-write", "mv": "file-write", "cp": "file-write",
+    "mkdir": "file-write", "rmdir": "file-write", "chmod": "file-write",
+    "chown": "file-write", "touch": "file-write", "ln": "file-write",
+    "sed": "file-write", "tee": "file-write", "truncate": "file-write",
+    "dd": "file-write", "tar": "file-write", "unzip": "file-write",
+    "zip": "file-write",
+    # network
+    "curl": "network", "wget": "network", "gh": "network",
+    "ssh": "network", "scp": "network", "rsync": "network",
+    "nc": "network", "ping": "network", "dig": "network",
+    "host": "network", "nslookup": "network",
+}
+
+# Multiplexer commands whose class hangs on the SUBcommand word (still
+# never an argument): {cmd: (subcommand → class, default class)}.
+GIT_READ_SUBS = {
+    "status", "log", "diff", "show", "blame", "shortlog", "reflog",
+    "describe", "rev-parse", "ls-files", "ls-remote", "ls-tree",
+    "cat-file", "grep",
+}
+BASH_MULTIPLEX_CLASS = {
+    # git subcommands outside the read set default to git-write
+    # (write-risky wins for branch/tag/stash-style ambiguity).
+    "git": ({s: "git-read" for s in GIT_READ_SUBS}, "git-write"),
+    "go": (
+        {"test": "test", "vet": "test",
+         "build": "build", "run": "build", "generate": "build",
+         "get": "pkg", "install": "pkg", "mod": "pkg"},
+        "other",
+    ),
+    "cargo": (
+        {"test": "test", "bench": "test",
+         "build": "build", "check": "build", "run": "build",
+         "clippy": "build",
+         "add": "pkg", "install": "pkg", "update": "pkg",
+         "remove": "pkg"},
+        "other",
+    ),
+    "npm": (
+        {"test": "test", "run": "build", "exec": "build"},
+        "pkg",  # install/i/ci/add/uninstall/update/…
+    ),
+    "pnpm": (
+        {"test": "test", "run": "build", "exec": "build"},
+        "pkg",
+    ),
+    "yarn": (
+        {"test": "test", "run": "build"},
+        "pkg",
+    ),
+    "bun": (
+        {"test": "test", "run": "build", "build": "build"},
+        "pkg",
+    ),
+}
+
+
+def classify_bash_command(command: str) -> tuple[str, bool] | None:
+    """Map a Bash command string to (bash_class, bash_multi).
+
+    Tokenizes on shell separators (&&, ||, ;, |, newline); classifies
+    each segment by its leading command word after stripping env-var
+    prefixes and sudo; the most write-risky class present wins
+    (BASH_CLASS_RANK order). bash_multi is True when segments span more
+    than one class. Only the command/subcommand WORD feeds the lookup —
+    no argument ever does, and nothing from the string is returned
+    beyond the closed enum. Returns None when no command word is found.
+    """
+    for sep in ("&&", "||", ";", "|", "\n"):
+        command = command.replace(sep, "\x00")
+    classes: set[str] = set()
+    for segment in command.split("\x00"):
+        words = segment.split()
+        # Strip env-var prefixes (FOO=bar) and sudo from the front.
+        while words and ("=" in words[0] or words[0] == "sudo"):
+            words.pop(0)
+        if not words:
+            continue
+        cmd = words[0].rsplit("/", 1)[-1]  # /usr/bin/git → git
+        mux = BASH_MULTIPLEX_CLASS.get(cmd)
+        if mux is not None:
+            sub_map, default = mux
+            sub = words[1] if len(words) > 1 else ""
+            classes.add(sub_map.get(sub, default))
+        else:
+            classes.add(BASH_CMD_CLASS.get(cmd, "other"))
+    if not classes:
+        return None
+    winner = min(classes, key=BASH_CLASS_RANK.index)
+    return winner, len(classes) > 1

cardinal_core/deviceflow.py

@@ -0,0 +1,192 @@
+"""Cardinal device-code consent flow and endpoint reachability probes.
+
+Shared verbatim by every adapter's cardinal-connect. `client_id` names the
+requesting plugin (e.g. "cardinal-codex-plugin") so the server can show
+which agent is asking for consent.
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Callable
+
+DEFAULT_POLL_TIMEOUT_SECS = 600
+DEFAULT_POLL_INTERVAL_SECS = 5
+INGEST_PROBE_RETRY_SLEEPS = (1.0, 2.0, 4.0, 8.0, 16.0, 32.0)
+
+
+class DeviceFlowError(RuntimeError):
+    """Raised for any unrecoverable device-flow failure; message is
+    user-presentable. Adapters decide how to exit (sys.exit for CLIs)."""
+
+
+def derive_deployment_env(host: str) -> str:
+    try:
+        hostname = urllib.parse.urlparse(host).hostname or ""
+    except Exception:
+        return "unknown"
+    if hostname == "app.cardinalhq.io":
+        return "prod"
+    if "dogfood" in hostname:
+        return "dogfood"
+    if "cardinalhq.io" in hostname:
+        return "cardinal"
+    return "customer"
+
+
+def _post_json(url: str, body: dict, timeout: int = 15) -> tuple[int, dict | None]:
+    payload = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=payload,
+        method="POST",
+        headers={"content-type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read()
+            return resp.status, json.loads(raw) if raw else None
+    except urllib.error.HTTPError as exc:
+        raw = exc.read() if hasattr(exc, "read") else b""
+        try:
+            return exc.code, json.loads(raw) if raw else None
+        except json.JSONDecodeError:
+            return exc.code, None
+
+
+def start_device_code(host: str, scopes: list[str], client_id: str) -> dict:
+    status, body = _post_json(
+        host.rstrip("/") + "/api/auth/device/code",
+        {
+            "client": client_id,
+            "scopes": scopes,
+            "hostname": socket.gethostname(),
+        },
+    )
+    if status != 201 or not body:
+        err = (body or {}).get("error", f"HTTP {status}")
+        desc = (body or {}).get("error_description", "")
+        raise DeviceFlowError(f"device-code init failed: {err}{(': ' + desc) if desc else ''}")
+    return body
+
+
+def poll_device_token(
+    host: str,
+    device_code: str,
+    client_id: str,
+    interval: int,
+    timeout: int,
+) -> dict:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        status, body = _post_json(
+            host.rstrip("/") + "/api/auth/device/token",
+            {"device_code": device_code, "client": client_id},
+            timeout=20,
+        )
+        body = body or {}
+        if status == 200:
+            return body
+        err = body.get("error", f"http_{status}")
+        if err == "authorization_pending":
+            time.sleep(interval)
+            continue
+        if err == "slow_down":
+            interval += 5
+            time.sleep(interval)
+            continue
+        if err == "access_denied":
+            raise DeviceFlowError("Request was denied in the browser.")
+        if err == "expired_token":
+            raise DeviceFlowError("Consent request expired before approval. Re-run cardinal-connect.")
+        desc = body.get("error_description", "")
+        raise DeviceFlowError(f"device-code failed: {err}{(': ' + desc) if desc else ''}")
+    raise DeviceFlowError("Timed out waiting for browser approval. Re-run cardinal-connect.")
+
+
+def verify_mcp_reachable(mcp_url: str | None, api_key: str | None) -> tuple[bool, str]:
+    if not mcp_url:
+        return False, "server returned no MCP URL"
+    if not api_key:
+        return False, "server returned no MCP API key"
+    req = urllib.request.Request(
+        mcp_url,
+        method="GET",
+        headers={"x-cardinalhq-api-key": api_key},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return resp.status not in (401, 403), f"HTTP {resp.status}"
+    except urllib.error.HTTPError as exc:
+        if exc.code in (401, 403):
+            return False, f"HTTP {exc.code} - MCP key invalid"
+        return True, f"HTTP {exc.code} - auth OK"
+    except (urllib.error.URLError, TimeoutError) as exc:
+        return False, f"network error: {exc}"
+
+
+def _ingest_probe_once(endpoint: str, api_key: str, api_header: str) -> tuple[bool, str]:
+    url = endpoint.rstrip("/") + "/v1/metrics"
+    req = urllib.request.Request(
+        url,
+        data=b"",
+        method="POST",
+        headers={
+            "content-type": "application/x-protobuf",
+            api_header: api_key,
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return resp.status not in (401, 403), f"HTTP {resp.status}"
+    except urllib.error.HTTPError as exc:
+        if exc.code in (401, 403):
+            return False, f"HTTP {exc.code} - ingest key invalid"
+        if exc.code < 500:
+            return True, f"HTTP {exc.code} on empty body - auth OK"
+        return False, f"HTTP {exc.code}"
+    except (urllib.error.URLError, TimeoutError) as exc:
+        return False, f"network error: {exc}"
+
+
+def verify_ingest_reachable(
+    ingest: dict | None,
+    log: Callable[[str], None] = print,
+    sleeps: tuple[float, ...] = INGEST_PROBE_RETRY_SLEEPS,
+) -> tuple[bool, str]:
+    """Probe the ingest endpoint. Retries the 401 case on the retry
+    ladder because a freshly minted key can take seconds to propagate;
+    `sleeps` is injectable so callers (and tests) can shorten it
+    (core 0.2.0 gap #7)."""
+    if not ingest:
+        return False, "server returned no ingest credential"
+    endpoint = ingest.get("endpoint")
+    api_key = ingest.get("api_key")
+    api_header = ingest.get("api_header") or "x-cardinalhq-api-key"
+    if not endpoint:
+        return False, "server returned no ingest endpoint"
+    if not api_key:
+        return False, "server returned no ingest API key"
+
+    last_msg = ""
+    for attempt in range(len(sleeps) + 1):
+        ok, msg = _ingest_probe_once(str(endpoint), str(api_key), str(api_header))
+        if ok:
+            return True, msg
+        last_msg = msg
+        if "HTTP 401" not in msg:
+            return False, msg
+        if attempt < len(sleeps):
+            sleep_s = sleeps[attempt]
+            log(
+                f"ingest key returned 401; retrying in {sleep_s:.0f}s "
+                f"(attempt {attempt + 2}/{len(sleeps) + 1})..."
+            )
+            time.sleep(sleep_s)
+    total = sum(sleeps)
+    return False, f"{last_msg} after ~{total:.0f}s; ingest key did not propagate"

cardinal_core/initiative.py

@@ -0,0 +1,135 @@
+"""Initiative resolution from git facts — pure logic, no I/O beyond git.
+
+One branch = one initiative. Branch names following the
+`<type-prefix>/<kebab-name>` convention classify exactly; protected
+branches are research/scoping; everything else gets a stable name with
+type 'feature'.
+
+Kept in lockstep with conductor's normalizeInitiativeName — this is now
+the single client-side copy (spec §Core module inventory).
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+
+PROTECTED_BRANCHES = frozenset({"main", "master", "develop", "trunk"})
+
+# Noise words that appear between `worktree-` and the real name in
+# EnterWorktree-style branches.
+WORKTREE_NOISE = frozenset({
+    "fix", "feat", "bug", "bugfix", "issue", "issues", "pr",
+})
+NUMERIC_SEGMENT_RE = re.compile(r"^\d+$")
+
+PREFIX_TO_TYPE = {
+    "feat": "feature",
+    "feature": "feature",
+    "perf": "feature",
+    "fix": "bugfix",
+    "bugfix": "bugfix",
+    "refactor": "refactor",
+    "cleanup": "refactor",
+    "infra": "infra",
+    "chore": "infra",
+    "test": "infra",
+    "tests": "infra",
+    "ci": "infra",
+    "build": "infra",
+    "deps": "infra",
+    "docs": "infra",
+    "doc": "infra",
+    "research": "research",
+    "spike": "research",
+}
+
+REMOTE_URL_RE = re.compile(r"(?:git@|https?://)([^:/]+)[:/]([^/]+)/(.+?)(?:\.git)?/?$")
+
+COMMAND_RE = re.compile(r"^\s*/([A-Za-z0-9][\w:-]*)")
+COMMAND_TAG_RE = re.compile(r"<command-name>\s*/?([\w:-]+)\s*</command-name>")
+
+
+def strip_worktree_noise(name: str) -> str:
+    """worktree-fix-1018-github-app-repo-picker → github-app-repo-picker.
+    Conservative: non-worktree names pass through verbatim; if nothing
+    real remains after the head, keep the original."""
+    if not name.startswith("worktree-"):
+        return name
+    segs = name.split("-")
+    i = 1
+    while i < len(segs) and (
+        segs[i] in WORKTREE_NOISE or NUMERIC_SEGMENT_RE.match(segs[i])
+    ):
+        i += 1
+    if i < len(segs):
+        return "-".join(segs[i:])
+    return name
+
+
+def resolve_initiative(branch: str | None) -> tuple[str | None, str]:
+    """(initiative_name, initiative_type) for a branch name."""
+    if not branch or branch == "HEAD":
+        return None, "research"
+    if branch in PROTECTED_BRANCHES:
+        return None, "research"
+    if "/" in branch:
+        prefix, _, rest = branch.partition("/")
+        mapped = PREFIX_TO_TYPE.get(prefix.lower())
+        if mapped and rest:
+            return strip_worktree_noise(rest), mapped
+    return strip_worktree_noise(branch), "feature"
+
+
+def canonical_repo(remote_url: str | None) -> str | None:
+    """'git@github.com:org/name.git' → 'org/name'."""
+    if not remote_url:
+        return None
+    m = REMOTE_URL_RE.match(remote_url.strip())
+    if not m:
+        return None
+    name = re.sub(r"\.git$", "", m.group(3))
+    return f"{m.group(2)}/{name}" if m.group(2) and name else None
+
+
+def detect_command(prompt: object) -> str | None:
+    """'/code-review --fix' → 'code-review'. Accepts the raw typed form
+    (anchored at start) and the expanded <command-name> tag form."""
+    if not isinstance(prompt, str):
+        return None
+    m = COMMAND_RE.match(prompt)
+    if m:
+        return m.group(1)
+    m = COMMAND_TAG_RE.search(prompt)
+    if m:
+        return m.group(1)
+    return None
+
+
+def git(args: list[str], cwd: str, timeout: float = 1.0) -> str | None:
+    """Best-effort git invocation; None on any failure."""
+    try:
+        out = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if out.returncode != 0:
+        return None
+    return out.stdout.strip() or None
+
+
+def is_git_repo(cwd: str) -> bool:
+    return git(["rev-parse", "--is-inside-work-tree"], cwd) == "true"
+
+
+def git_facts(cwd: str) -> tuple[str | None, str | None]:
+    """(repo 'org/name', branch) for cwd — best-effort."""
+    branch = git(["rev-parse", "--abbrev-ref", "HEAD"], cwd)
+    remote = git(["remote", "get-url", "origin"], cwd)
+    return canonical_repo(remote), branch