clink-cli 0.2.1__py3-none-any.whl

clink/parsers/base.py

@@ -0,0 +1,209 @@
+"""Parser interfaces for clink runner outputs."""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import math
+import re
+import unicodedata
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+MAX_METADATA_NUMBER = 2**53 - 1
+MAX_SOURCE_URLS = 20
+MAX_SOURCE_URL_LENGTH = 2048
+_MODEL_IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z")
+_AUTHENTICATION_SIGNATURE = re.compile(
+    r"\b(?:authentication[_ -](?:required|error|failed)|invalid[_ -](?:api[_ -]key|authentication)|"
+    r"unauthenticated|not[_ -](?:logged[_ -]in|authenticated)|please (?:log|sign) in|"
+    r"401 unauthorized|(?:http|status(?: code)?)\s*[:=]?\s*401)\b",
+    re.IGNORECASE,
+)
+_RATE_LIMIT_SIGNATURE = re.compile(
+    r"\b(?:rate[_ -]limit(?:ed|[_ -](?:exceeded|error))?|too[_ -]many[_ -]requests|"
+    r"quota[_ -](?:has[_ -]been[_ -])?exceeded|resource_exhausted|"
+    r"429 too many requests|(?:http|status(?: code)?)\s*[:=]?\s*429)\b",
+    re.IGNORECASE,
+)
+
+
+@dataclass
+class ParsedCLIResponse:
+    """Result of parsing CLI stdout/stderr."""
+
+    content: str
+    metadata: dict[str, Any]
+
+
+class ParserError(RuntimeError):
+    """Raised when CLI output cannot be parsed into a structured response."""
+
+    def __init__(self, message: str, code: str = "parse_error") -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def cli_failure(
+    *diagnostics: object, message: str = "CLI reported a failure", code: str = "parse_error"
+) -> ParserError:
+    """Classify known failure signatures without returning diagnostic text."""
+
+    # Only inspect bounded error fields, never arbitrary session/assistant bodies.
+    pending = [(value, 0) for value in diagnostics]
+    texts: list[str] = []
+    while pending and len(texts) < 32:
+        value, depth = pending.pop(0)
+        if isinstance(value, str):
+            texts.append(value[:8192])
+        elif isinstance(value, int) and not isinstance(value, bool):
+            if value == 401:
+                texts.append("status 401")
+            elif value == 429:
+                texts.append("status 429")
+        elif isinstance(value, dict) and depth < 3:
+            pending.extend(
+                (value[key], depth + 1)
+                for key in ("error", "errors", "code", "type", "message", "status")
+                if key in value
+            )
+        elif isinstance(value, list) and depth < 3:
+            pending.extend((part, depth + 1) for part in value[:16])
+
+    text = "\n".join(texts)
+    if _AUTHENTICATION_SIGNATURE.search(text):
+        return ParserError("CLI authentication is required", code="authentication_required")
+    if _RATE_LIMIT_SIGNATURE.search(text):
+        return ParserError("CLI rate limit was reached", code="rate_limited")
+    return ParserError(message, code=code)
+
+
+def load_json(text: str, *, allow_codex_web_search_ids: bool = False) -> object:
+    """Decode strict JSON without preserving raw input in parser exceptions."""
+
+    duplicate_ids: list[dict[str, Any]] = []
+
+    def unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        for key, value in pairs:
+            if key in result:
+                if (
+                    allow_codex_web_search_ids
+                    and key == "id"
+                    and isinstance(result[key], str)
+                    and isinstance(value, str)
+                ):
+                    duplicate_ids.append(result)
+                else:
+                    raise ValueError("Duplicate JSON key")
+            result[key] = value
+        return result
+
+    def reject_constant(_value: str) -> None:
+        raise ValueError("Non-finite JSON constant")
+
+    invalid = False
+    try:
+        result = json.loads(text, object_pairs_hook=unique_object, parse_constant=reject_constant)
+    except (ValueError, RecursionError):
+        invalid = True
+    if invalid:
+        raise ParserError("CLI returned malformed JSON")
+    if duplicate_ids:
+        # Codex rust-v0.166.0 flattens WebSearchItem.id into ThreadItem, which
+        # already has its own id. Both are opaque and never enter metadata.
+        # No other duplicate field, item type, or location is admitted.
+        item = result.get("item") if isinstance(result, dict) else None
+        if not (
+            isinstance(result, dict)
+            and result.get("type") in ("item.started", "item.updated", "item.completed")
+            and isinstance(item, dict)
+            and item.get("type") == "web_search"
+            and len(duplicate_ids) == 1
+            and duplicate_ids[0] is item
+        ):
+            raise ParserError("CLI returned malformed JSON")
+    return result
+
+
+def bounded_counts(value: object, fields: tuple[str, ...]) -> dict[str, int]:
+    """Copy only finite nonnegative integer telemetry from an explicit allowlist."""
+
+    if not isinstance(value, dict):
+        return {}
+    return {
+        key: count
+        for key in fields
+        if isinstance((count := value.get(key)), int)
+        and not isinstance(count, bool)
+        and 0 <= count <= MAX_METADATA_NUMBER
+    }
+
+
+def bounded_number(value: object) -> int | float | None:
+    """Return a bounded, nonnegative telemetry number, excluding booleans."""
+
+    if (
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and 0 <= value <= MAX_METADATA_NUMBER
+        and math.isfinite(value)
+    ):
+        return value
+    return None
+
+
+def model_identifier(value: object) -> str | None:
+    """Accept only bounded native model identifiers, excluding free-form bodies."""
+
+    if isinstance(value, str) and _MODEL_IDENTIFIER.fullmatch(value):
+        return value
+    return None
+
+
+def source_url(value: object) -> str | None:
+    """Keep bounded HTTP(S) source locations without credentials or URL tokens."""
+
+    if (
+        not isinstance(value, str)
+        or not value
+        or len(value) > MAX_SOURCE_URL_LENGTH
+        or "\\" in value
+        or any(character.isspace() or unicodedata.category(character) in ("Cc", "Cf", "Cs") for character in value)
+    ):
+        return None
+    try:
+        parts = urlsplit(value)
+        if (
+            parts.scheme not in ("http", "https")
+            or not parts.hostname
+            or parts.username is not None
+            or parts.password is not None
+        ):
+            return None
+        hostname = parts.hostname
+        if "%" in hostname:
+            return None
+        if ":" in hostname:
+            ipaddress.IPv6Address(hostname)
+        else:
+            ascii_host = hostname.encode("idna").decode("ascii").rstrip(".")
+            if len(ascii_host) > 253 or not all(
+                re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?", label) for label in ascii_host.split(".")
+            ):
+                return None
+        # Accessing port validates bracketed hosts and the numeric port range.
+        _ = parts.port
+    except (ValueError, UnicodeError):
+        return None
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, "", ""))
+
+
+class BaseParser:
+    """Base interface for CLI output parsers."""
+
+    name: str = "base"
+
+    def parse(self, stdout: str, stderr: str) -> ParsedCLIResponse:
+        raise NotImplementedError("Parsers must implement parse()")

clink/parsers/claude.py

@@ -0,0 +1,104 @@
+"""Parser for Claude CLI JSON output."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import (
+    BaseParser,
+    ParsedCLIResponse,
+    ParserError,
+    bounded_counts,
+    bounded_number,
+    cli_failure,
+    load_json,
+    model_identifier,
+)
+
+_USAGE_FIELDS = ("input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens")
+
+
+class ClaudeJSONParser(BaseParser):
+    """Require a successful terminal result from Claude's JSON envelope."""
+
+    name = "claude_json"
+
+    def parse(self, stdout: str, stderr: str) -> ParsedCLIResponse:
+        if not stdout.strip():
+            raise cli_failure(stderr, message="Claude CLI returned empty stdout")
+
+        loaded = load_json(stdout)
+        if isinstance(loaded, dict):
+            events = [loaded]
+        elif isinstance(loaded, list) and loaded and all(isinstance(event, dict) for event in loaded):
+            events = loaded
+        else:
+            raise ParserError("Claude CLI JSON must be an object or a nonempty array of objects")
+
+        for index, event in enumerate(events):
+            event_type = event.get("type")
+            subtype = event.get("subtype")
+            if (
+                not isinstance(event_type, str)
+                or not event_type
+                or (subtype is not None and not isinstance(subtype, str))
+            ):
+                raise ParserError("Claude CLI events must contain valid type fields")
+            if "status" in event and not isinstance(event["status"], str):
+                raise ParserError("Claude CLI event status must be textual")
+            if (
+                event_type == "error"
+                or event.get("status") in ("error", "failed", "cancelled", "aborted", "interrupted")
+                or event.get("is_error", False) is not False
+                or event.get("error") is not None
+                or event.get("errors")
+                or (isinstance(subtype, str) and subtype.lower().startswith("error"))
+            ):
+                raise cli_failure(event, event.get("result"), stderr, message="Claude CLI reported a failed result")
+            if event_type == "result" and index != len(events) - 1:
+                raise ParserError("Claude CLI emitted events after its terminal result")
+            message = event.get("message")
+            blocks = message.get("content") if isinstance(message, dict) else None
+            if isinstance(blocks, list):
+                for block in blocks:
+                    if not isinstance(block, dict):
+                        continue
+                    subtype = block.get("subtype")
+                    if block.get("type") == "error" or (
+                        block.get("type") == "tool_result"
+                        and (
+                            block.get("is_error", False) is not False
+                            or block.get("error") is not None
+                            or (isinstance(subtype, str) and subtype.lower().startswith("error"))
+                        )
+                    ):
+                        raise cli_failure(block, stderr, message="Claude CLI tool execution failed")
+
+        payload = events[-1]
+        if payload["type"] != "result" or payload.get("subtype") != "success":
+            raise cli_failure(payload, stderr, message="Claude CLI did not include a successful terminal result")
+        if payload.get("status", "success") not in ("completed", "success"):
+            raise ParserError("Claude CLI terminal status did not indicate success")
+
+        result = payload.get("result")
+        if not isinstance(result, str):
+            raise ParserError("Claude CLI result must be textual")
+        if not result.strip():
+            raise cli_failure(stderr, message="Claude CLI result was empty", code="empty_response")
+
+        metadata: dict[str, Any] = {}
+        for field in ("duration_ms", "duration_api_ms", "num_turns"):
+            number = bounded_number(payload.get(field))
+            if number is not None:
+                metadata[field] = number
+        usage = bounded_counts(payload.get("usage"), _USAGE_FIELDS)
+        if usage:
+            metadata["usage"] = usage
+
+        model_usage = payload.get("modelUsage")
+        if isinstance(model_usage, dict) and len(model_usage) == 1:
+            actual_model = model_identifier(next(iter(model_usage)))
+            if actual_model and isinstance(model_usage[actual_model], dict):
+                metadata["actual_model"] = actual_model
+
+        return ParsedCLIResponse(content=result.strip(), metadata=metadata)

clink/parsers/claude_native.py

@@ -0,0 +1,113 @@
+"""Parse native Claude NDJSON without retaining raw events or tool arguments."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from clink.native_contracts import ParsedNativeResponse
+from clink.parsers.base import ParserError, bounded_counts, bounded_number, cli_failure, load_json, model_identifier
+
+RESULT_CHARACTERS = 20000
+MAX_EVENTS = 16384
+_SESSION = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]{0,127}\Z")
+_SUBTYPE = re.compile(r"[A-Za-z][A-Za-z0-9_-]{0,63}\Z")
+_USAGE_FIELDS = ("input_tokens", "output_tokens", "cache_creation_input_tokens", "cache_read_input_tokens")
+
+
+def validate_session_id(value: str | None) -> str | None:
+    if value is not None and (not isinstance(value, str) or not _SESSION.fullmatch(value)):
+        raise ParserError("Claude native session identity is invalid")
+    return value
+
+
+class ClaudeNativeParser:
+    """Use terminal status; recoverable tool errors do not invalidate success."""
+
+    def parse(self, stdout: str, stderr: str = "") -> ParsedNativeResponse:
+        lines = [line for line in stdout.splitlines() if line.strip()]
+        if not lines or len(lines) > MAX_EVENTS:
+            raise ParserError("Claude native output was empty or exceeded the event limit")
+        terminal: dict[str, Any] | None = None
+        session_id = None
+        permission_denials = 0
+        tool_errors = 0
+        fatal = False
+        for line in lines:
+            event = load_json(line)
+            if not isinstance(event, dict) or not isinstance(event.get("type"), str) or not event["type"]:
+                raise ParserError("Claude native events must be JSON objects with a type")
+            if terminal is not None:
+                raise ParserError("Claude native output continued after its terminal result")
+            observed_session = event.get("session_id")
+            if observed_session is not None:
+                validate_session_id(observed_session)
+                if session_id is not None and session_id != observed_session:
+                    raise ParserError("Claude native output changed its session identity")
+                session_id = observed_session
+            subtype = event.get("subtype")
+            if subtype is not None and (not isinstance(subtype, str) or not _SUBTYPE.fullmatch(subtype)):
+                raise ParserError("Claude native event subtype is invalid")
+            if event["type"] == "system" and subtype == "permission_denied":
+                permission_denials += 1
+            elif event["type"] == "error":
+                fatal = True
+            elif event["type"] == "result":
+                terminal = event
+            message = event.get("message")
+            blocks = message.get("content") if isinstance(message, dict) else None
+            if isinstance(blocks, list):
+                tool_errors += sum(
+                    1
+                    for block in blocks
+                    if isinstance(block, dict) and block.get("type") == "tool_result" and block.get("is_error") is True
+                )
+        if terminal is None:
+            raise cli_failure(stderr, message="Claude native output had no terminal result")
+        if not isinstance(terminal.get("is_error"), bool):
+            raise ParserError("Claude native terminal error flag is invalid")
+        terminal_status = terminal.get("status", "success")
+        if not isinstance(terminal_status, str):
+            raise ParserError("Claude native terminal status is invalid")
+        denials = terminal.get("permission_denials", [])
+        if not isinstance(denials, list):
+            raise ParserError("Claude native permission denials must be an array")
+        # A denial can appear both in the stream and in the terminal summary.
+        permission_denials = max(permission_denials, len(denials))
+        metadata: dict[str, Any] = {
+            "tool_error_count": tool_errors,
+            "permission_denial_count": permission_denials,
+            "truncated": False,
+        }
+        for name in ("duration_ms", "duration_api_ms", "num_turns"):
+            number = bounded_number(terminal.get(name))
+            if number is not None:
+                metadata[name] = number
+        if usage := bounded_counts(terminal.get("usage"), _USAGE_FIELDS):
+            metadata["usage"] = usage
+        model_usage = terminal.get("modelUsage")
+        if isinstance(model_usage, dict) and len(model_usage) == 1:
+            actual_model = model_identifier(next(iter(model_usage)))
+            if actual_model is not None and isinstance(model_usage[actual_model], dict):
+                metadata["actual_model"] = actual_model
+        subtype = terminal.get("subtype")
+        if isinstance(subtype, str):
+            metadata["terminal_subtype"] = subtype
+        success = (
+            subtype == "success"
+            and terminal["is_error"] is False
+            and terminal_status in {"success", "completed"}
+            and terminal.get("error") is None
+            and not terminal.get("errors")
+            and not fatal
+        )
+        if success and session_id is None:
+            raise ParserError("Claude native successful result omitted its session identity")
+        state = "permission_needed" if permission_denials else "completed" if success else "failed"
+        content = terminal.get("result") if subtype == "success" else terminal.get("result", "")
+        if not isinstance(content, str):
+            raise ParserError("Claude native result must be textual")
+        metadata["truncated"] = len(content) > RESULT_CHARACTERS
+        if state == "failed":
+            metadata["error_code"] = cli_failure(terminal, stderr, code="native_error").code
+        return ParsedNativeResponse(state, content[:RESULT_CHARACTERS], session_id, metadata)