@tt-a1i/mco 0.1.2

package/runtime/cli.py

@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+from .config import ReviewConfig, ReviewPolicy, load_review_config
+from .review_engine import ReviewRequest, run_review
+
+
+def _render_user_readable_report(
+    command: str,
+    result_mode: str,
+    providers: List[str],
+    payload: Dict[str, object],
+    provider_results: Dict[str, Dict[str, object]],
+) -> str:
+    lines: List[str] = []
+    title = "Review" if command == "review" else "Run"
+    lines.append(f"{title} Result")
+    lines.append("")
+    lines.append("Execution Summary")
+    lines.append(f"- task_id: {payload['task_id']}")
+    lines.append(f"- decision: {payload['decision']}")
+    lines.append(f"- terminal_state: {payload['terminal_state']}")
+    lines.append(f"- providers: {', '.join(providers)}")
+    lines.append(
+        f"- provider_success/failure: {payload['provider_success_count']}/{payload['provider_failure_count']}"
+    )
+    lines.append(f"- findings_count: {payload['findings_count']}")
+    lines.append(f"- parse_success/failure: {payload['parse_success_count']}/{payload['parse_failure_count']}")
+    lines.append(f"- schema_valid_count: {payload['schema_valid_count']}")
+    lines.append("")
+    lines.append("Provider Details")
+    for provider in sorted(provider_results.keys()):
+        details = provider_results.get(provider, {})
+        success = bool(details.get("success"))
+        attempts = details.get("attempts")
+        final_error = details.get("final_error")
+        parse_reason = details.get("parse_reason")
+        findings_count = details.get("findings_count")
+        lines.append(
+            f"- {provider}: success={success}, attempts={attempts}, final_error={final_error}, parse_reason={parse_reason}, findings={findings_count}"
+        )
+        excerpt = str(details.get("output_excerpt", "")).strip()
+        if excerpt:
+            lines.append(f"  excerpt: {excerpt}")
+    lines.append("")
+    if result_mode in ("artifact", "both"):
+        lines.append("Artifacts")
+        lines.append(f"- artifact_root: {payload['artifact_root']}")
+    else:
+        lines.append("Artifacts")
+        lines.append("- artifact files are skipped in stdout mode")
+    return "\n".join(lines)
+
+
+def _parse_providers(raw: str) -> List[str]:
+    seen = set()
+    providers: List[str] = []
+    for item in raw.split(","):
+        value = item.strip()
+        if not value or value in seen:
+            continue
+        seen.add(value)
+        providers.append(value)
+    return providers
+
+
+def _parse_provider_timeouts(raw: str) -> Dict[str, int]:
+    result: Dict[str, int] = {}
+    if not raw.strip():
+        return result
+    for chunk in raw.split(","):
+        pair = chunk.strip()
+        if not pair or "=" not in pair:
+            continue
+        provider, timeout_text = pair.split("=", 1)
+        provider_name = provider.strip()
+        if not provider_name:
+            continue
+        try:
+            timeout = int(timeout_text.strip())
+        except Exception:
+            continue
+        if timeout <= 0:
+            continue
+        result[provider_name] = timeout
+    return result
+
+
+def _parse_paths(raw: str) -> List[str]:
+    paths = [item.strip() for item in raw.split(",") if item.strip()]
+    return paths if paths else ["."]
+
+
+def _parse_provider_permissions_json(raw: str) -> Dict[str, Dict[str, str]]:
+    if not raw.strip():
+        return {}
+    try:
+        payload = json.loads(raw)
+    except Exception:
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+
+    result: Dict[str, Dict[str, str]] = {}
+    for provider, permissions in payload.items():
+        provider_name = str(provider).strip()
+        if not provider_name or not isinstance(permissions, dict):
+            continue
+        normalized: Dict[str, str] = {}
+        for key, value in permissions.items():
+            key_name = str(key).strip()
+            if not key_name:
+                continue
+            normalized[key_name] = str(value)
+        if normalized:
+            result[provider_name] = normalized
+    return result
+
+
+def _merge_provider_permissions(
+    base: Dict[str, Dict[str, str]],
+    override: Dict[str, Dict[str, str]],
+) -> Dict[str, Dict[str, str]]:
+    merged: Dict[str, Dict[str, str]] = {provider: dict(values) for provider, values in base.items()}
+    for provider, permissions in override.items():
+        current = merged.get(provider, {})
+        current.update(permissions)
+        merged[provider] = current
+    return merged
+
+
+def _add_common_execution_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--repo", default=".", help="Repository root path")
+    parser.add_argument("--prompt", required=True, help="Task prompt")
+    parser.add_argument("--providers", default="", help="Comma-separated providers, e.g. claude,codex")
+    parser.add_argument("--config", default="", help="Config file path (.json or .yaml/.yml)")
+    parser.add_argument("--artifact-base", default="", help="Artifact base directory override")
+    parser.add_argument("--state-file", default="", help="Runtime state file override")
+    parser.add_argument("--task-id", default="", help="Optional stable task id")
+    parser.add_argument("--idempotency-key", default="", help="Optional stable idempotency key")
+    parser.add_argument("--target-paths", default=".", help="Comma-separated task scope paths")
+    parser.add_argument("--allow-paths", default="", help="Comma-separated allowed paths (default: .)")
+    parser.add_argument(
+        "--enforcement-mode",
+        choices=("strict", "best_effort"),
+        default="",
+        help="Permission enforcement mode (default: strict)",
+    )
+    parser.add_argument(
+        "--provider-permissions-json",
+        default="",
+        help="Provider permission mapping as JSON, e.g. '{\"codex\":{\"sandbox\":\"workspace-write\"}}'",
+    )
+    parser.add_argument(
+        "--strict-contract",
+        action="store_true",
+        help="Enforce strict findings JSON contract in review mode",
+    )
+    parser.add_argument(
+        "--max-provider-parallelism",
+        type=int,
+        default=None,
+        help="Override provider fan-out concurrency (0 means full parallelism)",
+    )
+    parser.add_argument(
+        "--provider-timeouts",
+        default="",
+        help="Comma-separated provider stall-timeout overrides, e.g. claude=120,codex=90",
+    )
+    parser.add_argument(
+        "--stall-timeout",
+        type=int,
+        default=None,
+        help="Override default stall timeout seconds (no output progress => cancel)",
+    )
+    parser.add_argument(
+        "--poll-interval",
+        type=float,
+        default=None,
+        help="Override poll interval seconds for provider status checks",
+    )
+    parser.add_argument(
+        "--review-hard-timeout",
+        type=int,
+        default=None,
+        help="Override review-mode hard deadline seconds (0 disables hard deadline)",
+    )
+    parser.add_argument(
+        "--result-mode",
+        choices=("artifact", "stdout", "both"),
+        default="artifact",
+        help="Result delivery mode: artifact files, stdout payload, or both",
+    )
+    parser.add_argument("--json", action="store_true", help="Print machine-readable result JSON")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="mco", description="MCO")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run = subparsers.add_parser("run", help="Run general multi-provider task execution")
+    _add_common_execution_args(run)
+
+    review = subparsers.add_parser("review", help="Run multi-provider review")
+    _add_common_execution_args(review)
+    return parser
+
+
+def _resolve_config(args: argparse.Namespace) -> ReviewConfig:
+    cfg = load_review_config(args.config or None)
+    providers = _parse_providers(args.providers) if args.providers else cfg.providers
+    artifact_base = args.artifact_base or cfg.artifact_base
+    state_file = args.state_file or cfg.state_file
+    provider_timeouts = dict(cfg.policy.provider_timeouts)
+    provider_timeouts.update(_parse_provider_timeouts(args.provider_timeouts))
+    allow_paths = _parse_paths(args.allow_paths) if args.allow_paths else list(cfg.policy.allow_paths)
+    provider_permissions = _merge_provider_permissions(
+        cfg.policy.provider_permissions,
+        _parse_provider_permissions_json(args.provider_permissions_json),
+    )
+    max_provider_parallelism = cfg.policy.max_provider_parallelism
+    if args.max_provider_parallelism is not None:
+        max_provider_parallelism = args.max_provider_parallelism
+    enforcement_mode = args.enforcement_mode or cfg.policy.enforcement_mode
+    stall_timeout_seconds = cfg.policy.stall_timeout_seconds
+    if args.stall_timeout is not None and args.stall_timeout > 0:
+        stall_timeout_seconds = args.stall_timeout
+    poll_interval_seconds = cfg.policy.poll_interval_seconds
+    if args.poll_interval is not None and args.poll_interval > 0:
+        poll_interval_seconds = args.poll_interval
+    review_hard_timeout_seconds = cfg.policy.review_hard_timeout_seconds
+    if args.review_hard_timeout is not None and args.review_hard_timeout >= 0:
+        review_hard_timeout_seconds = args.review_hard_timeout
+    enforce_findings_contract = cfg.policy.enforce_findings_contract or bool(args.strict_contract)
+
+    policy = ReviewPolicy(
+        timeout_seconds=cfg.policy.timeout_seconds,
+        stall_timeout_seconds=stall_timeout_seconds,
+        poll_interval_seconds=poll_interval_seconds,
+        review_hard_timeout_seconds=review_hard_timeout_seconds,
+        enforce_findings_contract=enforce_findings_contract,
+        max_retries=cfg.policy.max_retries,
+        high_escalation_threshold=cfg.policy.high_escalation_threshold,
+        require_non_empty_findings=cfg.policy.require_non_empty_findings,
+        max_provider_parallelism=max_provider_parallelism,
+        provider_timeouts=provider_timeouts,
+        allow_paths=allow_paths,
+        provider_permissions=provider_permissions,
+        enforcement_mode=enforcement_mode,
+    )
+    return ReviewConfig(providers=providers, artifact_base=artifact_base, state_file=state_file, policy=policy)
+
+
+def main(argv: List[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command not in ("run", "review"):
+        parser.error("unsupported command")
+        return 2
+
+    cfg = _resolve_config(args)
+    repo_root = str(Path(args.repo).resolve())
+    providers = [item for item in cfg.providers if item in ("claude", "codex", "gemini", "opencode", "qwen")]
+    if not providers:
+        print("No valid providers selected.", file=sys.stderr)
+        return 2
+
+    req = ReviewRequest(
+        repo_root=repo_root,
+        prompt=args.prompt,
+        providers=providers,  # type: ignore[arg-type]
+        artifact_base=str(Path(cfg.artifact_base).resolve()),
+        state_file=str(Path(cfg.state_file).resolve()),
+        policy=cfg.policy,
+        task_id=args.task_id or None,
+        idempotency_key=args.idempotency_key or None,
+        target_paths=[item.strip() for item in args.target_paths.split(",") if item.strip()],
+    )
+    review_mode = args.command == "review"
+    write_artifacts = args.result_mode in ("artifact", "both")
+    result = run_review(req, review_mode=review_mode, write_artifacts=write_artifacts)
+
+    payload = {
+        "command": args.command,
+        "task_id": result.task_id,
+        "artifact_root": result.artifact_root,
+        "decision": result.decision,
+        "terminal_state": result.terminal_state,
+        "provider_success_count": sum(1 for item in result.provider_results.values() if bool(item.get("success"))),
+        "provider_failure_count": sum(1 for item in result.provider_results.values() if not bool(item.get("success"))),
+        "findings_count": result.findings_count,
+        "parse_success_count": result.parse_success_count,
+        "parse_failure_count": result.parse_failure_count,
+        "schema_valid_count": result.schema_valid_count,
+        "dropped_findings_count": result.dropped_findings_count,
+        "created_new_task": result.created_new_task,
+    }
+    if args.result_mode == "artifact":
+        if args.json:
+            print(json.dumps(payload, ensure_ascii=True))
+        else:
+            print(
+                _render_user_readable_report(
+                    args.command,
+                    args.result_mode,
+                    providers,
+                    payload,
+                    result.provider_results,
+                )
+            )
+    else:
+        detailed_payload = dict(payload)
+        detailed_payload["result_mode"] = args.result_mode
+        detailed_payload["provider_results"] = result.provider_results
+        if args.json:
+            print(json.dumps(detailed_payload, ensure_ascii=True))
+        else:
+            print(
+                _render_user_readable_report(
+                    args.command,
+                    args.result_mode,
+                    providers,
+                    payload,
+                    result.provider_results,
+                )
+            )
+
+    if result.decision == "FAIL":
+        return 2
+    if review_mode and result.decision == "INCONCLUSIVE":
+        return 3
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/config.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+DEFAULT_PROVIDER_TIMEOUTS: Dict[str, int] = {
+}
+
+
+@dataclass(frozen=True)
+class ReviewPolicy:
+    timeout_seconds: int = 180
+    stall_timeout_seconds: int = 900
+    poll_interval_seconds: float = 1.0
+    review_hard_timeout_seconds: int = 1800
+    enforce_findings_contract: bool = False
+    max_retries: int = 1
+    high_escalation_threshold: int = 1
+    require_non_empty_findings: bool = True
+    max_provider_parallelism: int = 0
+    provider_timeouts: Dict[str, int] = field(default_factory=lambda: dict(DEFAULT_PROVIDER_TIMEOUTS))
+    allow_paths: List[str] = field(default_factory=lambda: ["."])
+    provider_permissions: Dict[str, Dict[str, str]] = field(default_factory=dict)
+    enforcement_mode: str = "strict"
+
+
+@dataclass(frozen=True)
+class ReviewConfig:
+    providers: List[str] = field(default_factory=lambda: ["claude", "codex"])
+    artifact_base: str = "reports/review"
+    state_file: str = ".mco/state.json"
+    policy: ReviewPolicy = field(default_factory=ReviewPolicy)
+
+
+def _as_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in ("true", "1", "yes", "y", "on"):
+            return True
+        if lowered in ("false", "0", "no", "n", "off"):
+            return False
+    return default
+
+
+def _to_policy(payload: Dict[str, Any]) -> ReviewPolicy:
+    raw_provider_timeouts = payload.get("provider_timeouts", {})
+    provider_timeouts: Dict[str, int] = dict(DEFAULT_PROVIDER_TIMEOUTS)
+    if isinstance(raw_provider_timeouts, dict):
+        for key, value in raw_provider_timeouts.items():
+            provider = str(key).strip()
+            if not provider:
+                continue
+            try:
+                timeout = int(value)
+            except Exception:
+                continue
+            if timeout <= 0:
+                continue
+            provider_timeouts[provider] = timeout
+
+    try:
+        max_parallel = int(payload.get("max_provider_parallelism", 0))
+    except Exception:
+        max_parallel = 0
+    if max_parallel < 0:
+        max_parallel = 0
+
+    raw_allow_paths = payload.get("allow_paths", ["."])
+    allow_paths: List[str]
+    if isinstance(raw_allow_paths, str):
+        allow_paths = [item.strip() for item in raw_allow_paths.split(",") if item.strip()]
+    elif isinstance(raw_allow_paths, list):
+        allow_paths = [str(item).strip() for item in raw_allow_paths if str(item).strip()]
+    else:
+        allow_paths = ["."]
+    if not allow_paths:
+        allow_paths = ["."]
+
+    raw_provider_permissions = payload.get("provider_permissions", {})
+    provider_permissions: Dict[str, Dict[str, str]] = {}
+    if isinstance(raw_provider_permissions, dict):
+        for provider, permissions in raw_provider_permissions.items():
+            provider_name = str(provider).strip()
+            if not provider_name or not isinstance(permissions, dict):
+                continue
+            normalized: Dict[str, str] = {}
+            for key, value in permissions.items():
+                key_name = str(key).strip()
+                if not key_name:
+                    continue
+                normalized[key_name] = str(value)
+            if normalized:
+                provider_permissions[provider_name] = normalized
+
+    enforcement_mode = str(payload.get("enforcement_mode", "strict")).strip().lower()
+    if enforcement_mode not in ("strict", "best_effort"):
+        enforcement_mode = "strict"
+
+    try:
+        stall_timeout_seconds = int(payload.get("stall_timeout_seconds", 900))
+    except Exception:
+        stall_timeout_seconds = 900
+    if stall_timeout_seconds <= 0:
+        stall_timeout_seconds = 900
+
+    try:
+        poll_interval_seconds = float(payload.get("poll_interval_seconds", 1.0))
+    except Exception:
+        poll_interval_seconds = 1.0
+    if poll_interval_seconds <= 0:
+        poll_interval_seconds = 1.0
+
+    try:
+        review_hard_timeout_seconds = int(payload.get("review_hard_timeout_seconds", 1800))
+    except Exception:
+        review_hard_timeout_seconds = 1800
+    if review_hard_timeout_seconds < 0:
+        review_hard_timeout_seconds = 1800
+
+    return ReviewPolicy(
+        timeout_seconds=int(payload.get("timeout_seconds", 180)),
+        stall_timeout_seconds=stall_timeout_seconds,
+        poll_interval_seconds=poll_interval_seconds,
+        review_hard_timeout_seconds=review_hard_timeout_seconds,
+        enforce_findings_contract=_as_bool(payload.get("enforce_findings_contract", False), False),
+        max_retries=int(payload.get("max_retries", 1)),
+        high_escalation_threshold=int(payload.get("high_escalation_threshold", 1)),
+        require_non_empty_findings=_as_bool(payload.get("require_non_empty_findings", True), True),
+        max_provider_parallelism=max_parallel,
+        provider_timeouts=provider_timeouts,
+        allow_paths=allow_paths,
+        provider_permissions=provider_permissions,
+        enforcement_mode=enforcement_mode,
+    )
+
+
+def _normalize_payload(payload: Dict[str, Any]) -> ReviewConfig:
+    policy_payload = payload.get("policy", {})
+    if not isinstance(policy_payload, dict):
+        policy_payload = {}
+    providers = payload.get("providers", ["claude", "codex"])
+    if isinstance(providers, str):
+        providers = [item.strip() for item in providers.split(",") if item.strip()]
+    if not isinstance(providers, list):
+        providers = ["claude", "codex"]
+    providers = [str(item).strip() for item in providers if str(item).strip()]
+    if not providers:
+        providers = ["claude", "codex"]
+
+    return ReviewConfig(
+        providers=providers,
+        artifact_base=str(payload.get("artifact_base", "reports/review")),
+        state_file=str(payload.get("state_file", ".mco/state.json")),
+        policy=_to_policy(policy_payload),
+    )
+
+
+def load_review_config(config_path: Optional[str]) -> ReviewConfig:
+    if not config_path:
+        return ReviewConfig()
+    path = Path(config_path)
+    if not path.exists():
+        raise FileNotFoundError(f"config file not found: {config_path}")
+
+    suffix = path.suffix.lower()
+    raw_text = path.read_text(encoding="utf-8")
+    if suffix == ".json":
+        payload = json.loads(raw_text)
+        if not isinstance(payload, dict):
+            raise ValueError("config root must be an object")
+        return _normalize_payload(payload)
+
+    if suffix in (".yaml", ".yml"):
+        try:
+            import yaml  # type: ignore
+        except Exception as exc:
+            raise RuntimeError(
+                "YAML config requires pyyaml. Install with: pip install pyyaml, or use a .json config."
+            ) from exc
+        payload = yaml.safe_load(raw_text)
+        if not isinstance(payload, dict):
+            raise ValueError("config root must be a map")
+        return _normalize_payload(payload)
+
+    raise ValueError(f"unsupported config format: {config_path}")

package/runtime/contracts.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, Protocol, Sequence, runtime_checkable
+
+from .types import ErrorKind
+
+
+ProviderId = Literal["claude", "codex", "gemini", "opencode", "qwen"]
+CapabilityTier = Literal["C0", "C1", "C2", "C3", "C4", "C5", "C6"]
+TaskAttemptState = Literal["PENDING", "STARTED", "SUCCEEDED", "FAILED", "CANCELLED", "EXPIRED"]
+
+PROVIDER_IDS: Sequence[ProviderId] = ("claude", "codex", "gemini", "opencode", "qwen")
+CAPABILITY_TIERS: Sequence[CapabilityTier] = ("C0", "C1", "C2", "C3", "C4", "C5", "C6")
+
+
+@dataclass(frozen=True)
+class CapabilitySet:
+    tiers: List[CapabilityTier]
+    supports_native_async: bool
+    supports_poll_endpoint: bool
+    supports_resume_after_restart: bool
+    supports_schema_enforcement: bool
+    min_supported_version: str
+    tested_os: List[Literal["macos", "linux", "windows"]]
+
+
+@dataclass(frozen=True)
+class ProviderPresence:
+    provider: ProviderId
+    detected: bool
+    binary_path: Optional[str]
+    version: Optional[str]
+    auth_ok: bool
+    reason: str = ""
+
+
+@dataclass(frozen=True)
+class TaskInput:
+    task_id: str
+    prompt: str
+    repo_root: str
+    target_paths: List[str]
+    required_capabilities: List[CapabilityTier] = field(default_factory=lambda: ["C1", "C2"])
+    optional_capabilities: List[CapabilityTier] = field(default_factory=list)
+    timeout_seconds: int = 600
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class TaskRunRef:
+    task_id: str
+    provider: ProviderId
+    run_id: str
+    artifact_path: str
+    started_at: str
+    pid: Optional[int] = None
+    session_id: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class TaskStatus:
+    task_id: str
+    provider: ProviderId
+    run_id: str
+    attempt_state: TaskAttemptState
+    completed: bool
+    heartbeat_at: Optional[str]
+    output_path: Optional[str]
+    error_kind: Optional[ErrorKind] = None
+    exit_code: Optional[int] = None
+    message: str = ""
+
+
+@dataclass(frozen=True)
+class NormalizeContext:
+    task_id: str
+    provider: ProviderId
+    repo_root: str
+    raw_ref: str
+
+
+@dataclass(frozen=True)
+class Evidence:
+    file: str
+    line: Optional[int]
+    snippet: str
+    symbol: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class NormalizedFinding:
+    task_id: str
+    provider: ProviderId
+    finding_id: str
+    severity: Literal["critical", "high", "medium", "low"]
+    category: Literal["bug", "security", "performance", "maintainability", "test-gap"]
+    title: str
+    evidence: Evidence
+    recommendation: str
+    confidence: float
+    fingerprint: str
+    raw_ref: str
+
+
+@runtime_checkable
+class ProviderAdapter(Protocol):
+    id: ProviderId
+
+    def detect(self) -> ProviderPresence:
+        ...
+
+    def capabilities(self) -> CapabilitySet:
+        ...
+
+    def run(self, input_task: TaskInput) -> TaskRunRef:
+        ...
+
+    def poll(self, ref: TaskRunRef) -> TaskStatus:
+        ...
+
+    def cancel(self, ref: TaskRunRef) -> None:
+        ...
+
+    def normalize(self, raw: Any, ctx: NormalizeContext) -> List[NormalizedFinding]:
+        ...
+

package/runtime/errors.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import re
+from typing import List
+
+from .types import ErrorKind, WarningKind
+
+
+def detect_warnings(stderr: str) -> List[WarningKind]:
+    text = stderr.lower()
+    warnings: List[WarningKind] = []
+    if "mcp" in text and ("failed to start" in text or "auth required" in text):
+        warnings.append(WarningKind.PROVIDER_WARNING_MCP_STARTUP)
+    return warnings
+
+
+def classify_error(exit_code: int, stderr: str) -> ErrorKind:
+    text = stderr.lower()
+
+    if exit_code in (124, 142) or "timeout" in text or "timed out" in text:
+        return ErrorKind.RETRYABLE_TIMEOUT
+
+    if "rate limit" in text or "429" in text:
+        return ErrorKind.RETRYABLE_RATE_LIMIT
+
+    if any(token in text for token in ("connection reset", "temporary failure", "network", "econnreset", "ehostunreach")):
+        return ErrorKind.RETRYABLE_TRANSIENT_NETWORK
+
+    if any(token in text for token in ("auth", "invalid api key", "401", "oauth", "unauthorized")):
+        return ErrorKind.NON_RETRYABLE_AUTH
+
+    if any(token in text for token in ("unsupported capability", "not supported", "unknown arguments")):
+        return ErrorKind.NON_RETRYABLE_UNSUPPORTED_CAPABILITY
+
+    if any(token in text for token in ("invalid input", "schema", "missing required", "validation failed", "invalid type")):
+        return ErrorKind.NON_RETRYABLE_INVALID_INPUT
+
+    # A parsing failure after command success is also represented as normalization error.
+    if re.search(r"(parse|deserialize|json).*fail", text) or "normalization" in text:
+        return ErrorKind.NORMALIZATION_ERROR
+
+    return ErrorKind.NORMALIZATION_ERROR
+